R.1
sbx commands
Every verb of sbx 0.47.0 in the four groups of sbx --help, with its purpose, the flags that matter, its scope, and the section that explains it.
The root help of sbx 0.47.0 lists 31 commands in four groups: Sandbox, Management, Experimental, and Other. The vendored tree holds 115 help pages, one for each command and subcommand that answered --help. The tables below keep the order of the root help. Scope says where a verb runs: local sandboxes through sandboxd, cloud sandboxes through sbx --cloud, or both. sbx --cloud --help hides daemon, prune, settings, and skills, and attach, ttl, and volume run only with --cloud (conflict C47).
Three flags apply to every command.
| Global flag | Meaning |
|---|---|
--cloud | Dispatch to the Docker Cloud Sandboxes API instead of the local sandboxd |
-D, --debug | Enable debug logging |
-h, --help | Print the help of the command |
Sandbox commands
| Command | Purpose | Flags that matter | Scope | Section |
|---|---|---|---|---|
attach SANDBOX | Attach a terminal to a cloud sandbox, and start it first when it is stopped | --detach-keys (default Ctrl-\) | cloud only | §7.1 |
cp SRC DST | Copy a file or a directory between a sandbox and the host, with one side written as SANDBOX:PATH | -L, --follow-link | both | §2.2 |
create AGENT|SANDBOX_KIT [PATH...] | Create a sandbox for one of the 11 agents or from a kit reference, without attaching | --name (default <agent>-<workdir>), --clone, --cpus (0 is auto), -m, --memory (default 50% of host memory, 512 MiB to 32 GiB), -e, --env, --env-file, --deny-network, -p, --publish, --pull always|missing|never (default always), --skills off|readonly|readwrite (default readonly), --static-mcp, -t, --template, --profile, --kit (experimental), --kit-arg, --kit-args-file, -q | both | §2.1 |
create <agent> [PATH...] | The eight subcommands claude, codex, cursor, devin, docker-agent, gemini, opencode, shell, with the same flags, and cagent as an alias of docker-agent | the flags of create | both | §2.1 |
create with --cloud | Create a cloud sandbox with no host workspace, 2 CPUs and 4 GiB unless sized | --allow-network, --image-ref, --on-timeout stop|restart|delete, --platform, --ttl, -v, --volume (experimental) | cloud only | §7.1 |
exec SANDBOX COMMAND | Run a command inside a sandbox, and start a stopped one first | -i, -t, -u, --user, -w, --workdir, -e, --env-file, --privileged, --detach-keys. -d is not supported. -d, --user, and --privileged are rejected with --cloud | both | §2.2 |
ls | List sandboxes with agent, status, published ports, and workspace | --json, -q | both | §2.1 |
move SANDBOX | Move a sandbox between the host and the cloud as a filesystem image | --to local|cloud, --name (default moved- plus the source name), --ttl (15s to 24h), --on-timeout stop|delete, -f | both | §7.1 |
ports SANDBOX | List, publish, or unpublish sandbox ports | --publish, --unpublish, --json. A port without a protocol binds tcp4 | both | §2.2 |
prune | Remove all stopped sandboxes and their sandbox-scoped secrets | --dry-run, --filter until=TIMESTAMP, -f, --json | local only | §2.1 |
rm [SANDBOX...] | Remove sandboxes, their containers, git worktrees, state, and scoped secrets | --all (disabled with --cloud), -f | both | §2.1 |
run [AGENT|SANDBOX_KIT] [PATH...] [-- AGENT_ARGS...] | Run an agent and create the sandbox when it does not exist | the flags of create, plus -d, --detached, --rm, --name to re-attach, --new (cloud), --detach-keys (cloud). --clone works only at creation | both | §2.1 |
stop SANDBOX... | Stop sandboxes and keep their state | none | both | §2.1 |
ttl [+DURATION] SANDBOX | Print or extend the TTL of a cloud sandbox under its 24 hour ceiling | --json | cloud only | §7.1 |
The 11 agent names that run and create accept are claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, and shell. Only eight of them have a create subcommand, because copilot, droid, and kiro are public kits (conflict C9).
Management commands
| Command | Purpose | Flags that matter | Scope | Section |
|---|---|---|---|---|
daemon start | Start sandboxd | -d, --detach, --policy allow-all|balanced|deny-all | local only | §2.4 |
daemon stop, daemon restart | Stop or restart sandboxd | none | local only | §2.4 |
daemon status | Print the daemon state, its socket, and its log path | --json | local only | §2.4 |
daemon log-level set <target> <level> | Set the log level of proxy, general, or all | none | local only | §2.4 |
diagnose | Run the 13 installation checks | --json, -o json|github-issue, --upload | both | §2.4 and §7.4 |
mcp add <name> (--url | --command) | Register an MCP server from a remote endpoint, a registry URL, a manifest URL, a dhi.io image, or a host command | --url, --command, --args, --dir, --local, --header, --client-id, --oauth-authorization-server, --scope, --no-scope, --resource, --callback-port, --skip-auth, --skip-ssrf-check, --disable-http2 | both | §3.6 |
mcp auth [server-name] | Authorize or reauthorize remote servers through the hosted control plane | --all, --scope, --no-scope, --verbose, --format text|json, --json | both | §3.6 |
mcp auth rm, mcp auth status | Remove hosted OAuth credentials, or show their status without starting OAuth | --all, -f (rm only), --format, --json | both | §3.6 |
mcp inspect <name> | Show one registration, its headers, and the effective resource value | --json | both | §3.6 |
mcp load <name> --sandbox S | Attach a registered server to a running sandbox, with a tools/list_changed notification to the agent | --sandbox (required) | both | §3.6 |
mcp ls | List registered servers under the gateway that serves them | --json, -q | both | §3.6 |
mcp rm <name> | Remove a registration | -f | both | §3.6 |
policy init <allow-all|balanced|deny-all> | Set the global network policy once, before the first sandbox | --sandbox (cloud only) | both | §3.3 |
policy allow network RESOURCES | Add an allow rule for hosts, domains, IP addresses, or CIDR prefixes, TCP by default | --sandbox, --protocol tcp|udp | both | §3.3 |
policy deny network RESOURCES | Add a deny rule, TCP and UDP by default, which wins over allow | --sandbox, --protocol tcp|udp | both | §3.3 |
policy check network TARGET | Ask the daemon authorizer whether a host and port is allowed, without sending anything | --sandbox, --protocol, --verbose, --json | both | §3.3 |
policy inspect <policy-or-rule> | Show one policy or one rule with its RULE_ID and removal command | --json | both | §3.3 |
policy log [SANDBOX] | Show which hosts the proxy allowed or blocked, with rule, proxy type, and count | --json, --limit, -q, --type all|network|filesystem (filesystem logs are not supported yet) | both | §3.4 |
policy ls [SANDBOX] | List policies, one overview row per policy, or the rules of one sandbox | --wide, --json, --source local|org|kit, --decision allow|deny, --type, --created-via default|added|provisioned|approval, --profile, --protocol, --include-inactive | both | §3.3 and §7.2 |
policy profile ls | List the profiles that remote governance policies provide | --json, -q | both | §7.2 |
policy reset | Delete the local policy store and stop the daemon, or delete the cloud account policy | -f | both | §3.3 |
policy rm network | Remove a rule by RULE_ID or by resource | --id, --resource, --sandbox, -f | both | §3.3 |
reset | Return sbx to a freshly installed state, including secrets and the sign-in | -f, --preserve-secrets | local only | §2.4 |
secret set [SERVICE] | Store a service secret for one of 13 services, a dynamic source, or a registry credential | -t, stdin, --ref, --command, --refresh (default 55m), --no-verify, --show-error, --oauth (openai only locally), --sandbox, -f, --registry, --username, --password-stdin, --registry-auth-endpoint, --all-sandboxes | both | §3.5 |
secret import [SERVICE] | Import secrets found in host environment variables, with a last four character preview | --all, --force, --dry-run | both | §3.5 |
secret ls | List stored secrets across global and sandbox scopes | -g, --sandbox, --service, --json, -q | both | §3.5 |
secret rm [SERVICE] | Remove a secret, a registry credential, or every secret | --sandbox, --all, --all-sandboxes, --registry, -f. The examples also show --placeholder, which the flag list omits | both | §3.5 |
secret set-custom | Store a secret for a service sbx does not know, behind a placeholder the proxy swaps | --host (repeatable), --env, --value, -t, --command, --ref, --placeholder ({rand} suffix), --refresh, --sandbox. Cloud only: --header, --format, --name | both, experimental | §3.5 |
settings get <key> | Print one evaluated value | --json | local only | §2.5 |
settings list | List every setting with value, type, source, restart flag, and description | --json, --no-trunc | local only | §2.5 and R.3 |
settings set <key> <value>, settings unset <key> | Write or remove a user override | none | local only | §2.5 |
template save SANDBOX TAG | Save a snapshot into the sandbox runtime image store | -o, --output (also export a tar), --capture-mode disk|all (cloud), -d, --description (cloud) | both | §2.3 |
template load FILE [NAME] | Load a tar into the image store, or upload it as a cloud template | --cpus and --memory-mib (required with --cloud, must name a billable shape), --capture-mode, --description | both | §2.3 |
template ls, template rm TAG|ID|NAME | List or remove template images | --json, -q, -f | both | §2.3 |
template inspect NAME|ID | Show the full metadata of one cloud template | --json | cloud only in v1 | §2.3 |
tui | Open the interactive dashboard | none | both | §1.1 |
volume create|inspect|ls|rm | Manage persistent cloud volumes, saved as a snapshot when a sandbox exits | --json, -q, -f | cloud only | §7.1 |
sbx with no command opens interactive mode, and sbx tui opens the dashboard by name (conflict C44).
Experimental commands
Each of these prints the line EXPERIMENTAL: this command may change or be removed in future releases. at the top of its help.
| Command | Purpose | Flags that matter | Scope | Section |
|---|---|---|---|---|
env create [PATH...] | Provision the secrets and bindings of an sbxenv.yaml and create the sandbox | -y, --auto-approve, --clone, --env-arg, --env-args-file, --kit-arg, --kit-args-file, --name, --skip-host-commands | both, experimental | §4.4 |
env run [PATH...] | Create when needed, then attach to the environment sandbox | the flags of env create, plus -d, --detached | both, experimental | §4.4 |
env plan [PATH...] | Print what applying the file would change, and change nothing | --clone, --env-arg, --kit-arg, --name, --skip-host-commands | both, experimental | §4.4 |
env exec [PATH...] -- COMMAND | Run a command in the environment sandbox | the flags of exec, plus --env-arg, --env-args-file, --name | both, experimental | §4.4 |
env rm [PATH...] | Remove the environment sandbox and the secrets it provisioned | -f, --prune-bindings, --env-arg, --name, --skip-host-commands | both, experimental | §4.4 |
kit add SANDBOX REFERENCE | Recreate a sandbox with a mixin appended to its kit list | --kit-arg, --kit-args-file | both, experimental | §4.3 |
kit builder status|rm | Show or remove the sbx-kit-builder sandbox and its build cache | -f (rm) | local, experimental | §4.3 |
kit builder history export|inspect|logs|ls|rm|trace | Run the matching docker buildx history command inside the builder sandbox | pass-through | local, experimental | §4.3 |
kit inspect REFERENCE | Load and display a kit from a directory, ZIP, OCI reference, or git repository | --json, --kit-arg, --kit-args-file | both, experimental | §4.2 |
kit pack DIRECTORY | Validate a spec.yaml directory and package it as a ZIP | -o, --output (default <name>.zip) | both, experimental | §4.3 |
kit provenance REFERENCE | Print the SLSA provenance attached to an OCI kit, UNSIGNED or VERIFIED | --key, --certificate-identity, --certificate-identity-regexp, --certificate-oidc-issuer, --certificate-oidc-issuer-regexp, --insecure-ignore-tlog, --json | both, experimental | §4.3 |
kit pull REFERENCE | Pull a v1 ZIP or v2 tar.gz kit artifact from an HTTPS registry | -o, --output | both, experimental | §4.3 |
kit push DIRECTORY REFERENCE | Package and push a spec.yaml kit, and attach SLSA provenance as an OCI referrer | --sign, --key, --identity-token, --identity-token-file, --tlog-upload (default true) | both, experimental | §4.3 |
kit sign REFERENCE | Sign a kit with a cosign-compatible Sigstore signature, keyless by default | --key, --identity-token, --identity-token-file, --tlog-upload | both, experimental | §4.3 |
kit validate REFERENCE | Check that a directory, ZIP, or git reference is a valid kit | --json, --kit-arg, --kit-args-file | both, experimental | §4.3 |
kit verify REFERENCE | Verify a signature on a directory, a git reference, or an OCI kit | --key, the four --certificate-* flags, --insecure-ignore-tlog, --json | both, experimental | §4.3 |
setup | Detect agent secrets in the host environment and import the accepted ones | none | local, experimental | §3.5 |
setup ssh, setup ssh remove | Write or remove the SSH client config that makes ssh <name>.sbx work | --alias (default *.sbx) | local, experimental | §2.4 |
skills add <repository> | Install skills from a git repository or owner/repo shorthand into the shared store | -s, --skill, -f | local, experimental | §4.5 |
skills import | Import skills from six agent directories on the host | --dry-run, -f | local, experimental | §4.5 |
skills ls, skills rm <skill>..., skills update [skill]... | List, remove, or refresh installed skills | --json, -q, -f | local, experimental | §4.5 |
sbx kit ls is not a command, and the probe answered unknown command (conflict C46). The six kit builder history pages in the vendored tree hold an error instead of help text. The daemon could not bind its socket under the capture sandbox.
Other commands
| Command | Purpose | Flags that matter | Scope | Section |
|---|---|---|---|---|
completion | Generate the autocompletion script for a shell | its help page is not in the vendored tree | both | none |
help | Help about any command | its help page is not in the vendored tree | both | none |
login | Sign in to Docker | --username, --password-stdin | both | §1.1 |
logout | Stop running local sandboxes and sign out | -y, --yes | local only | §1.1 |
version | Print the CLI version, and with --json the server and runtime component versions | --json | both | §2.4 |
Names that appear in text but not in the tree
The help of secret set names sbx mount, and the docs name sbx ssh proxy, sbx policy approval, --model, --provider, and --usb (conflict C16). None of them has a page in the vendored tree. The manual documents only what --help prints, and §2.4 names the hidden commands once. Every sbx ... --help call also tried to open a TLS connection to login.docker.com:443 during the capture. The capture sandbox refused the connection, and the printed text did not change (our source record).
Docker Sandboxes (sbx) and Docker Agent (docker-agent) sbx 0.47.0, docker-agent 1.149.0 · bf4169c · 2026-10-07 · Edition 2026.10