osb CLI Command Reference for OpenSandbox

The osb CLI is organized into command groups, each covering a distinct area of sandbox management. This reference lists every command with its flags, arguments, and working examples drawn directly from the source. All examples assume you have already configured the CLI with osb config init — see the CLI Overview for setup instructions.

Global Flags

These flags apply to the root osb command and override any config file or environment variable setting for the current invocation.

Flag	Description
`--api-key`	Override the API key for authentication (`OPEN_SANDBOX_API_KEY` env var).
`--domain`	Override the server domain (e.g. `localhost:8080`) (`OPEN_SANDBOX_DOMAIN` env var).
`--protocol`	Protocol to use: `http` or `https`.
`--request-timeout`	HTTP request timeout in seconds (integer).
`--use-server-proxy` / `--no-use-server-proxy`	Route execd and endpoint traffic through the sandbox server proxy.
`--config`	Path to an alternate config file.
`-v`, `--verbose`	Enable verbose/debug output.
`--no-color`	Disable colored output.

The output format flag -o / --output is per-command, not global. Pass it after the subcommand name (e.g. osb sandbox list -o json).

osb sandbox

sandbox create

Create a new sandbox from a container image. The image is required unless you have set defaults.image in the config file.

osb sandbox create --image python:3.12 --timeout 30m -o json

Flags:

Flag	Description
`--image`, `-i`	Container image (e.g. `python:3.12`). Uses `defaults.image` from config if omitted.
`--timeout`, `-t`	Sandbox lifetime: duration like `10m` or `1h`, `none` for manual cleanup, or omit to use config/SDK default.
`--entrypoint`	Entrypoint argv item. Repeat to build the full list.
`--env`, `-e`	Environment variable as `KEY=VALUE`. Repeatable.
`--metadata`, `-m`	Metadata key-value pair as `KEY=VALUE`. Repeatable.
`--extension`	Extension parameter as `KEY=VALUE`. Repeatable.
`--resource`	Resource limit as `KEY=VALUE` (e.g. `cpu=1`, `memory=2Gi`). Repeatable.
`--image-auth-username`	Registry username for a private image.
`--image-auth-password`	Registry password or token for a private image.
`--network-policy-file`	Path to a network policy JSON file.
`--volumes-file`	Path to a volumes JSON file (list of volume objects).
`--credential-proxy`	Enable Credential Vault transparent proxy. Requires `--network-policy-file`.
`--skip-health-check`	Skip waiting for sandbox readiness.
`--ready-timeout`	Max time to wait for readiness (e.g. `30s`).

Examples:

osb sandbox create --image python:3.12

If you set config defaults first, subsequent create commands can omit the flags:

osb config set defaults.image python:3.12
osb config set defaults.timeout 30m
osb sandbox create -o json

sandbox list

List sandboxes, optionally filtered by state, metadata, or page.

osb sandbox list
osb sandbox list -o json
osb sandbox list --state running --state paused

Flag	Description
`--state`, `-s`	Filter by sandbox state (e.g. `running`, `paused`). Case-insensitive. Repeatable.
`--metadata`, `-m`	Metadata filter as `KEY=VALUE`. Repeatable.
`--page`	Page number (1-indexed).
`--page-size`	Items per page.

sandbox get

Fetch full details for a specific sandbox by ID.

osb sandbox get <sandbox-id> -o json

Argument	Description
`sandbox-id`	The sandbox ID returned by `sandbox create` or `sandbox list`.

sandbox kill

Terminate one or more sandboxes immediately.

osb sandbox kill <sandbox-id>
osb sandbox kill <sandbox-id> -o json
osb sandbox kill <sandbox-id-1> <sandbox-id-2> -o json

Multiple sandbox IDs are accepted in a single call.

sandbox pause

Pause a running sandbox, preserving its state for later resumption.

osb sandbox pause <sandbox-id>
osb sandbox pause <sandbox-id> -o json

sandbox resume

Resume a previously paused sandbox.

osb sandbox resume <sandbox-id>
osb sandbox resume <sandbox-id> -o json

Flag	Description
`--skip-health-check`	Skip waiting for sandbox readiness after resume.
`--resume-timeout`	Max time to wait for readiness after resume (e.g. `30s`).

sandbox renew

Extend the expiration time of a sandbox.

osb sandbox renew <sandbox-id> --timeout 1h -o json

Flag	Description
`--timeout`, `-t`	Required. New TTL duration (e.g. `30m`, `2h`).

sandbox health

Check whether a sandbox is healthy and ready to accept commands.

osb sandbox health <sandbox-id>
osb sandbox health <sandbox-id> -o json

sandbox metrics

Retrieve resource usage metrics for a running sandbox.

osb sandbox metrics <sandbox-id>
osb sandbox metrics <sandbox-id> --watch -o raw

Flag	Description
`--watch`	Stream metrics updates in real time.

sandbox endpoint

Get the public network endpoint URL for a port exposed by the sandbox.

osb sandbox endpoint <sandbox-id> --port 8080 -o json

Flag	Description
`--port`, `-p`	Required. The port number to resolve to an endpoint URL.

osb command

command run

Run a command inside a sandbox. Always use -- to separate osb flags from the sandbox command payload.Foreground (default): streams stdout and stderr directly to your terminal. Only -o raw is accepted.

osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
osb command run <sandbox-id> -o raw -- sh -lc 'echo ready'

Background: returns a tracked execution object immediately. Accepts -o table, json, or yaml.

osb command run <sandbox-id> --background -o json -- sh -c "sleep 10; echo done"

Flag	Description
`--background`, `-d`	Run in background and return an execution ID.
`--workdir`, `-w`	Working directory inside the sandbox.
`--timeout`, `-t`	Command timeout (e.g. `30s`, `5m`).

command status

Check the status of a background command execution.

osb command status <sandbox-id> <execution-id> -o json

command logs

Retrieve logs from a background command execution.

osb command logs <sandbox-id> <execution-id> -o json
osb command logs <sandbox-id> <execution-id> -o raw

Flag	Description
`--cursor`	Integer cursor for incremental log reads.

command interrupt

Interrupt a running foreground or background command.

osb command interrupt <sandbox-id> <execution-id>

command session (persistent shell)

Persistent shell sessions maintain environment state — exported variables, working directory changes, and shell history — across multiple session run calls.

# Create a session
osb command session create <sandbox-id> --workdir /workspace -o json

# Run commands in the session (state is preserved between calls)
osb command session run <sandbox-id> <session-id> -o raw -- pwd
osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'

# Delete the session when finished
osb command session delete <sandbox-id> <session-id> -o json

session create flags:

Flag	Description
`--workdir`, `-w`	Initial working directory for the session.

session run flags:

Flag	Description
`--workdir`, `-w`	Working directory override for this run.
`--timeout`, `-t`	Command timeout (e.g. `30s`, `5m`).

osb file

file write

Write content to a file in the sandbox. Pass content inline with -c or pipe it from stdin.

osb file write <sandbox-id> /workspace/hello.txt -c "hello" -o json

Reading from stdin:

cat local-script.py | osb file write <sandbox-id> /workspace/script.py

Flag	Description
`--content`, `-c`	Content to write. Reads from stdin if omitted.
`--encoding`	File encoding (default: `utf-8`).
`--mode`	Permission mode as an integer (e.g. `644`, `755`).
`--owner`	File owner.
`--group`	File group.

file cat

Read and print a file from the sandbox.

osb file cat <sandbox-id> /workspace/hello.txt -o raw

Flag	Description
`--encoding`	File encoding (default: `utf-8`).
`-o`	Only `raw` is supported.

file upload

Upload a local file to a path inside the sandbox.

osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json

Argument	Description
`local_path`	Path to the local file (must exist).
`remote_path`	Destination path inside the sandbox.

file download

Download a file from the sandbox to local disk.

osb file download <sandbox-id> /workspace/result.json ./result.json -o json

Argument	Description
`remote_path`	Source path inside the sandbox.
`local_path`	Destination path on the local filesystem.

file search

Search for files in the sandbox by glob pattern.

osb file search <sandbox-id> /workspace --pattern "*.py" -o json

Flag	Description
`--pattern`, `-p`	Required. Glob pattern to match filenames.

file info

Get metadata (size, permissions, modification time) for one or more sandbox paths.

osb file info <sandbox-id> /workspace/main.py -o json
osb file info <sandbox-id> /workspace/main.py /workspace/utils.py -o json

Multiple paths are accepted in a single call.

file chmod

Change permissions on a file in the sandbox.

osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json

Flag	Description
`--mode`	Required. Permission mode as an integer (e.g. `755`, `644`).
`--owner`	File owner.
`--group`	File group.

file replace

Replace a string within a file in place.

osb file replace <sandbox-id> /workspace/app.py --old "old_value" --new "new_value" -o json

Flag	Description
`--old`	Required. The string to search for.
`--new`	Required. The replacement string.

file rm and file mv

Delete one or more files, or move/rename a file.

# Delete one or more files
osb file rm <sandbox-id> /workspace/temp.txt
osb file rm <sandbox-id> /workspace/a.txt /workspace/b.txt

# Move or rename
osb file mv <sandbox-id> /workspace/old-name.py /workspace/new-name.py

file mkdir and file rmdir

Create or remove directories inside the sandbox.

# Create one or more directories
osb file mkdir <sandbox-id> /workspace/output /workspace/logs

# Remove one or more directories
osb file rmdir <sandbox-id> /workspace/output

file mkdir flags:

Flag	Description
`--mode`	Directory permission mode as an integer.
`--owner`	Directory owner.
`--group`	Directory group.

osb egress

egress get

Retrieve the current runtime egress policy for a sandbox.

osb egress get <sandbox-id> -o json

egress patch

Patch egress rules at runtime using merge semantics. Rules are specified as ACTION=TARGET pairs.

osb egress patch <sandbox-id> --rule allow=pypi.org --rule deny=internal.example.com -o json

Flag	Description
`--rule`	Required. Rule in `allow=TARGET` or `deny=TARGET` form. Repeatable.

Verify the change takes effect by running a connectivity test inside the sandbox:

osb command run <sandbox-id> -o raw -- curl -I https://pypi.org

osb diagnostics

--scope is required for all diagnostics commands. Common scopes for logs are lifecycle (manager logs) and container (sandbox stdout). Common scopes for events are lifecycle and runtime.

Some server builds may return DIAGNOSTICS_NOT_IMPLEMENTED for scoped diagnostics until the stable backend implementation is enabled. Prefer osb diagnostics over osb devops for all stable API-backed log and event collection.

diagnostics logs

Retrieve diagnostic logs for a sandbox.

osb diagnostics logs <sandbox-id> --scope container -o raw
osb diagnostics logs <sandbox-id> --scope lifecycle -o json
osb diagnostics logs <sandbox-id> --scope container -o yaml

Flag	Description
`--scope`, `-s`	Required. Log scope: `lifecycle`, `container`, or a server-defined scope.

-o raw prints the inline log text, or the content URL if the diagnostic is delivered as a temporary URL.

diagnostics events

Retrieve diagnostic events for a sandbox.

osb diagnostics events <sandbox-id> --scope lifecycle -o raw
osb diagnostics events <sandbox-id> --scope runtime -o raw
osb diagnostics events <sandbox-id> --scope runtime -o json

Flag	Description
`--scope`, `-s`	Required. Event scope: `lifecycle`, `runtime`, or a server-defined scope.

devops inspect / devops summary (legacy)

Legacy experimental diagnostics. Prefer osb diagnostics for stable API-backed output.

osb devops inspect <sandbox-id> -o raw
osb devops summary <sandbox-id> -o raw

osb config

config init

Create the default config file at ~/.opensandbox/config.toml with empty values.

osb config init

To use a non-default location, pass --config at the root level:

osb --config /tmp/dev.toml config init

config set

Set a single config value by its dot-path key.

osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.api_key <your-api-key>
osb config set defaults.image python:3.12
osb config set defaults.timeout 30m

config show

Print the resolved configuration, including values from the config file and SDK defaults.

osb config show
osb config show -o json

osb skills

skills list

List all available bundled skills and their current installation status across all supported targets.

osb skills list
osb skills list -o json

skills show

Print the content of a specific bundled skill.

osb skills show sandbox-lifecycle

skills install

Install one or more bundled skills for a target agent tool. The install is non-interactive and idempotent — re-running reports already_present or updated instead of prompting.

# Install a single skill for Claude (project scope)
osb skills install sandbox-lifecycle --target claude --scope project

# Install all bundled skills globally for Codex
osb skills install --all-builtins --target codex --scope global

# Install for Cursor with JSON output (useful in scripts)
osb skills install sandbox-lifecycle --target cursor --scope project -o json

Flag	Description
`--target`, `-t`	Required. Target agent tool: `claude`, `cursor`, `codex`, `copilot`, `windsurf`, `cline`, `opencode`, or `all`.
`--scope`	Required. `project` (current directory) or `global` (home directory).
`--all-builtins`	Install all five bundled skills at once.
`--force`, `-f`	Accepted for compatibility. Installs are already non-interactive and idempotent.

skills uninstall

Remove a previously installed skill from a target.

osb skills uninstall sandbox-troubleshooting --target claude --scope global

Flag	Description
`--target`, `-t`	Required. Target agent tool (same choices as `install`).
`--scope`	Required. `project` or `global`.

osb credential-vault

credential-vault commands

The Credential Vault stores secrets inside the sandbox egress sidecar. You must create the sandbox with --credential-proxy and an explicit --network-policy-file before writing vault state.

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.

# Create vault state from a file
osb credential-vault create <sandbox-id> --file vault.yaml -o json

# Read current vault state
osb credential-vault get <sandbox-id> -o json

# Patch vault state
osb credential-vault patch <sandbox-id> --file mutation.yaml -o json

# List individual credentials and bindings
osb credential-vault credential list <sandbox-id> -o json
osb credential-vault binding list <sandbox-id> -o json

# Delete vault state
osb credential-vault delete <sandbox-id> -o json

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

osb CLI Command Reference for OpenSandbox

Global Flags

osb sandbox

osb command

osb file

osb egress

osb diagnostics

osb config

osb skills

osb credential-vault

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Global Flags

​osb sandbox

​osb command

​osb file

​osb egress

​osb diagnostics

​osb config

​osb skills

​osb credential-vault

Build docs developers (and LLMs) love

Global Flags

osb sandbox

osb command

osb file

osb egress

osb diagnostics

osb config

osb skills

osb credential-vault