# OpenSandbox CLI `osb` is the command-line interface for OpenSandbox. It is 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 - manage sandbox-local Credential Vault state - collect low-level diagnostics - install OpenSandbox-specific skills for coding agents It uses the OpenSandbox Python SDK under the hood and is intended to be the shortest path from a terminal to a working sandbox workflow. ## Install Choose one: ```bash pip install opensandbox-cli ``` ```bash uv tool install opensandbox-cli ``` ```bash pipx install opensandbox-cli ``` Confirm the install: ```bash osb --help osb --version ``` ## Before You Start Make sure an OpenSandbox server is reachable. If you are running locally, start the server first and then point the CLI at it. ```bash opensandbox-server ``` ## Quick Start ### 1. Initialize config ```bash osb config init osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set connection.api_key osb config show -o json ``` If you want a non-default config file, choose it at the root command level for the whole invocation: ```bash osb --config /tmp/dev.toml config init osb --config /tmp/dev.toml config set connection.domain localhost:8080 osb --config /tmp/dev.toml config show -o json ``` ### 2. Create a sandbox ```bash osb sandbox create --image python:3.12 --timeout 30m -o json ``` If you set defaults first, later create commands can be shorter: ```bash osb config set defaults.image python:3.12 osb config set defaults.timeout 30m osb sandbox create -o json ``` ### 3. Verify it is usable ```bash osb sandbox get -o json osb sandbox health -o json ``` ### 4. Run a command inside the sandbox Use `--` before the sandbox command payload. ```bash osb command run -o raw -- python -c "print(1 + 1)" ``` ### 5. Read or write a file ```bash osb file write /workspace/hello.txt -c "hello" -o json osb file cat /workspace/hello.txt -o raw ``` ### 6. Clean up ```bash osb sandbox kill -o json ``` ## Common Tasks ### Create sandboxes Basic: ```bash osb sandbox create --image python:3.12 ``` Private image: ```bash osb sandbox create \ --image my-registry.example.com/team/app:latest \ --image-auth-username alice \ --image-auth-password ``` Manual cleanup mode: ```bash osb sandbox create --image python:3.12 --timeout none ``` Explicit entrypoint argv: ```bash osb sandbox create \ --image python:3.12 \ --entrypoint python \ --entrypoint -m \ --entrypoint http.server ``` Create with network policy and volumes: ```bash osb sandbox create \ --image python:3.12 \ --network-policy-file network-policy.json \ --volumes-file volumes.json ``` Create with Credential Vault proxy enabled: ```bash osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json ``` ### List and inspect sandboxes ```bash osb sandbox list osb sandbox list -o json osb sandbox list --state running --state paused osb sandbox get -o json osb sandbox metrics osb sandbox metrics --watch -o raw ``` ### Expose a service ```bash osb sandbox endpoint --port 8080 -o json ``` ### Run commands Foreground streaming: ```bash osb command run -o raw -- sh -lc 'echo ready' ``` Tracked background execution: ```bash osb command run --background -o json -- sh -c "sleep 10; echo done" osb command status

-o json osb command logs

-o json ``` Persistent shell session: ```bash osb command session create --workdir /workspace -o json osb command session run

-o raw -- pwd osb command session run

-o raw -- export FOO=bar osb command session run

-o raw -- sh -c 'echo $FOO' osb command session delete

-o json ``` ### Work with files ```bash osb file upload ./local.txt /workspace/local.txt -o json osb file download /workspace/result.json ./result.json -o json osb file search /workspace --pattern "*.py" -o json osb file info /workspace/main.py -o json osb file replace /workspace/app.py --old old --new new -o json osb file chmod /workspace/script.sh --mode 755 -o json ``` ### Manage runtime egress policy Inspect current policy: ```bash osb egress get -o json ``` Patch specific rules: ```bash osb egress patch --rule allow=pypi.org --rule deny=internal.example.com -o json ``` If you are debugging connectivity, verify behavior with an actual command: ```bash osb command run -o raw -- curl -I https://pypi.org ``` ### Manage Credential Vault Credential Vault operations call the sandbox egress sidecar through the Python SDK. Create the sandbox with `--credential-proxy` and an explicit network policy before writing vault state. ```bash osb credential-vault create --file vault.yaml -o json osb credential-vault get -o json osb credential-vault patch --file mutation.yaml -o json osb credential-vault credential list -o json osb credential-vault binding list -o json osb credential-vault delete -o json ``` Use `--file -` to read a JSON/YAML payload from stdin. Do not pass plaintext credential values as command-line flags; keep them in the payload stream or file. ### Collect diagnostics Use the stable diagnostics commands for API-backed log and event descriptors. ```bash osb diagnostics events --scope lifecycle -o raw osb diagnostics events --scope runtime -o raw osb diagnostics logs --scope container -o raw osb diagnostics logs --scope lifecycle -o json osb diagnostics events --scope runtime -o json osb diagnostics logs --scope container -o yaml ``` `--scope` is required for stable diagnostics. Common scopes are `lifecycle` and `container` for logs, and `lifecycle` and `runtime` for events. Raw output prints inline diagnostic text, or the content URL when diagnostics are delivered as a temporary URL. Structured CLI output follows the SDK/Python field style, for example `content_url`, `content_length`, and `expires_at`. Some server builds may return `DIAGNOSTICS_NOT_IMPLEMENTED` for scoped diagnostics until the stable backend implementation is enabled. Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events` for stable API-backed log and event collection. ```bash osb devops inspect -o raw osb devops summary -o raw ``` ## Output Formats Output selection is command-scoped, not global. - `table`: human-readable tables and panels - `json`: machine-readable JSON - `yaml`: machine-readable YAML - `raw`: unformatted text or streaming output Examples: ```bash osb sandbox list -o json osb sandbox list -o yaml osb file cat /workspace/hello.txt -o raw ``` Not every command supports every format. Use `--help` on the specific command when in doubt. ## Command Groups The main command groups are: - `osb sandbox`: lifecycle management - `osb command`: command execution and persistent sessions - `osb file`: file and directory operations - `osb egress`: runtime egress policy - `osb diagnostics`: stable diagnostics logs and events - `osb devops`: experimental legacy diagnostics - `osb config`: local CLI configuration - `osb skills`: bundled skills for AI tools Explore them directly: ```bash osb sandbox --help osb command --help osb file --help osb skills --help ``` ## Agent Skills The CLI ships with built-in OpenSandbox skills for coding agents and agent-oriented tools. Bundled skills: - `sandbox-lifecycle` - `command-execution` - `file-operations` - `network-egress` - `sandbox-troubleshooting` Supported targets: | Target | Install location | | --- | --- | | `claude` | `./.claude/skills/` or `~/.claude/skills/` | | `cursor` | `./.cursor/rules/` or `~/.cursor/rules/` | | `codex` | `./.codex/skills//SKILL.md` or `~/.codex/skills//SKILL.md` | | `copilot` | `./.github/copilot-instructions.md` or `~/.github/copilot-instructions.md` | | `windsurf` | `./.windsurfrules` or `~/.windsurfrules` | | `cline` | `./.clinerules` or `~/.clinerules` | | `opencode` | `./.agents/skills//SKILL.md` or `~/.agents/skills//SKILL.md` | Common flows: ```bash osb skills list osb skills show sandbox-lifecycle osb skills install sandbox-lifecycle --target codex --scope project osb skills install --all-builtins --target codex --scope global osb skills uninstall sandbox-troubleshooting --target claude --scope global ``` For scripts or agents, use structured output: ```bash osb skills install sandbox-lifecycle --target codex --scope project -o json ``` ## Configuration Model The CLI resolves configuration in this order: 1. root CLI flags such as `--api-key`, `--domain`, `--protocol`, `--request-timeout`, `--config` 2. environment variables such as `OPEN_SANDBOX_API_KEY` and `OPEN_SANDBOX_DOMAIN` 3. config file, defaulting to `~/.opensandbox/config.toml` 4. SDK defaults Config commands: ```bash osb config init osb config show osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set defaults.image python:3.12 osb config set defaults.timeout 30m ``` Example config file: ```toml [connection] api_key = "your-api-key" domain = "localhost:8080" protocol = "http" request_timeout = 30 use_server_proxy = false [output] color = true [defaults] image = "python:3.12" timeout = "30m" ``` ## Development For local development in this monorepo: ```bash cd cli uv sync uv run osb --help uv run pytest ``` This repository uses a local `uv` source override for the OpenSandbox Python SDK, so running from `cli/` will resolve against the checked-out SDK in the monorepo.