SandboxOS CLI

sandboxos (short alias: sbx) is the command-line interface for managing sandboxes. It's built for the common day-to-day flows:

• create and manage sandboxes
• run commands inside a sandbox
• read and modify sandbox files
• inspect runtime egress policy
• collect low-level diagnostics
• install sandbox skills for coding agents

It uses the opensandbox Python SDK under the hood and is the shortest path from a terminal to a working sandbox workflow.

Install

pip install sandboxos

or with a tool installer:

uv tool install sandboxos
# or
pipx install sandboxos

Confirm the install:

sandboxos --help
sandboxos --version

Configuration

The CLI reads connection settings, in order of precedence:

1. Command-line flags (--api-key, --domain, --protocol, ...)
2. Environment variables (SANDBOXOS_API_KEY, SANDBOXOS_DOMAIN, SANDBOXOS_PROTOCOL, SANDBOXOS_REQUEST_TIMEOUT, SANDBOXOS_USE_SERVER_PROXY)
3. Config file at ~/.sandboxos/config.toml

sandboxos config init
sandboxos config set connection.domain localhost:8080
sandboxos config set connection.protocol http
sandboxos config set connection.api_key <your-api-key>
sandboxos config show -o json

Point at a non-default config for a whole invocation:

sandboxos --config /tmp/dev.toml config show -o json

Quick start

# Create a sandbox
sandboxos sandbox create --image python:3.12 --timeout 30m -o json

# Run a command inside it (payload after --)
sandboxos command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

# Read/write a file
sandboxos file write <sandbox-id> /workspace/hello.txt -c "hello" -o json
sandboxos file cat   <sandbox-id> /workspace/hello.txt -o raw

# Clean up
sandboxos sandbox kill <sandbox-id> -o json

Command groups

• sandboxos sandbox — lifecycle management
• sandboxos command — command execution and persistent sessions
• sandboxos file — file and directory operations
• sandboxos egress — runtime egress policy
• sandboxos diagnostics — stable diagnostics logs and events
• sandboxos devops — experimental legacy diagnostics
• sandboxos config — local CLI configuration
• sandboxos skills — bundled skills for AI tools

Run sandboxos <group> --help for details.

Output formats

Output selection is command-scoped via -o: table (default), json, yaml, raw. Not every command supports every format — use --help on the specific command when in doubt.

Requirements

• Python 3.10+
• A reachable sandbox server
• The opensandbox SDK (installed automatically)

License

Licensed under the Apache License, Version 2.0. See LICENSE.