#sandbox-cli command reference

Every command and subcommand of sandbox-cli, as sandbox-cli COMMAND --help prints it. Flags go before --; everything after it is the sandbox's command. sandbox-cli completion (shell completion scripts) and sandbox-cli help are cobra's own and not listed.

Setting up what these commands talk to is in self-hosting.md, local-macos.md and, for the gateway-only commands (ssh, job, service, secret, org, gateway), fleet.md.

Global flags:

#Commands

#sandbox-cli agent

Run a coding agent in a sandbox, keeping its login between runs.

sandbox-cli agent [command]

Runs a coding agent in a new sandbox, in the sandbox user's home, like `run`.
On top of `run`, the agent's login is restored into the sandbox and saved again
when the run ends, and the agent's own environment variables are forwarded when
set — or, where one is not, the API key saved for it in Studio's Agents screen
(~/.config/sandbox/agent-keys.json). The sandbox needs no repository: ask the
agent to clone one.

Leading sandbox flags are consumed; everything after them, or after --, goes
to the agent.

Subcommands: claude, cline, codex, copilot, cursor, devin, gemini, goose, kilocode, ls, opencode, openhands, qwen, state, wait.

Examples:

sandbox-cli agent claude
sandbox-cli agent claude --network none -- --resume
sandbox-cli agent codex --fallback claude -- exec "clone github.com/you/app and fix its failing test"

#sandbox-cli agent claude

Run claude in a new sandbox.

sandbox-cli agent claude [sandbox-flags] [--] [claude-args...]

#sandbox-cli agent cline

Run cline in a new sandbox.

sandbox-cli agent cline [sandbox-flags] [--] [cline-args...]

#sandbox-cli agent codex

Run codex in a new sandbox.

sandbox-cli agent codex [sandbox-flags] [--] [codex-args...]

#sandbox-cli agent copilot

Run copilot in a new sandbox.

sandbox-cli agent copilot [sandbox-flags] [--] [copilot-args...]

#sandbox-cli agent cursor

Run cursor in a new sandbox.

sandbox-cli agent cursor [sandbox-flags] [--] [cursor-args...]

#sandbox-cli agent devin

Run devin in a new sandbox.

sandbox-cli agent devin [sandbox-flags] [--] [devin-args...]

#sandbox-cli agent gemini

Run gemini in a new sandbox.

sandbox-cli agent gemini [sandbox-flags] [--] [gemini-args...]

#sandbox-cli agent goose

Run goose in a new sandbox.

sandbox-cli agent goose [sandbox-flags] [--] [goose-args...]

#sandbox-cli agent kilocode

Run kilocode in a new sandbox.

sandbox-cli agent kilocode [sandbox-flags] [--] [kilocode-args...]

#sandbox-cli agent ls

List the agents, whether each can run unattended, and whether a login is saved.

sandbox-cli agent ls

#sandbox-cli agent opencode

Run opencode in a new sandbox.

sandbox-cli agent opencode [sandbox-flags] [--] [opencode-args...]

#sandbox-cli agent openhands

Run openhands in a new sandbox.

sandbox-cli agent openhands [sandbox-flags] [--] [openhands-args...]

#sandbox-cli agent qwen

Run qwen in a new sandbox.

sandbox-cli agent qwen [sandbox-flags] [--] [qwen-args...]

#sandbox-cli agent state

Say what each agent is doing: working, blocked (waiting for you), idle, done or failed.

sandbox-cli agent state [SANDBOX...] [flags]

Reports each agent sandbox's state from evidence, never from the agent's wording:
whether its process has exited, who spoke last in its conversation, how long
ago, and whether it has a terminal somebody can answer at. A quiet agent with a
terminal is blocked — waiting for you; without one it is idle. Where the
evidence runs out (no conversation yet, or an agent whose format is not read)
the answer is unknown. --why says what each state means.

Flags:

#sandbox-cli agent wait

Wait until an agent is in one of the given states (blocked, idle, done, failed, …).

sandbox-cli agent wait SANDBOX --state STATE [--state STATE...] [flags]

Polls the agent's state until it is one of --state, then prints it and exits 0.
A timeout exits 2 and says which state the agent was actually in: it is not a
failure of the agent, and a script that treats it as one will stop work that was
merely slow. A sandbox that is gone ends the wait with an error, unless stopped
was one of the states asked for.

Examples:

sandbox-cli agent wait fix-auth --state blocked --state done --state failed --timeout 30m

Flags:

#sandbox-cli agent-run

Run an agent on a prompt on a gateway's fleet, unattended; prints the job id.

sandbox-cli agent-run AGENT PROMPT [flags]

Starts AGENT in its headless mode on PROMPT, in a fresh sandbox the gateway
makes and takes down: a job of one run (sandbox-cli job). Your saved login
does not come along; the agent authenticates with an API key you keep on the
gateway as a secret, named with --secret:

  sandbox-cli secret set ANTHROPIC_API_KEY < key.txt
  sandbox-cli agent-run claude "fix the failing test" --secret ANTHROPIC_API_KEY --wait

The agent must be in the image (or installable from it). With --wait, waits,
prints the run's output and exits with the agent's exit code.

Agents: claude, cline, codex, gemini, opencode.

Flags:

#sandbox-cli attach

Attach your terminal to a sandbox's process; closing the terminal, or Ctrl-C without one, detaches and leaves it running.

sandbox-cli attach SANDBOX [flags]

Flags:

#sandbox-cli context

Choose which sandboxd the CLI talks to: local, self-hosted, or cloud.

sandbox-cli context [command]

Subcommands: add, ls, rm, use.

#sandbox-cli context add

Add a context: https://host:port with --token-file, or unix:///path.

sandbox-cli context add NAME ENDPOINT [flags]

Flags:

#sandbox-cli context ls

List contexts; * marks the current one.

sandbox-cli context ls

#sandbox-cli context rm

Remove a context.

sandbox-cli context rm NAME

#sandbox-cli context use

Make NAME the current context.

sandbox-cli context use NAME

#sandbox-cli doctor

Check the current context's sandboxd and say what it offers.

sandbox-cli doctor [flags]

Flags:

#sandbox-cli events

Show a sandbox's audit events: what it was asked to do and how it ended.

sandbox-cli events SANDBOX [flags]

Prints the events sandboxd recorded for a sandbox: creation with its policy and
labels, every process with its argv and exit code, files read and written,
network changes, and how it ended. Environment variables appear by name only.
A terminated sandbox is still answered by id after the server has forgotten it.

Flags:

#sandbox-cli exec

Run a command in a running sandbox.

sandbox-cli exec SANDBOX -- COMMAND [ARGS...] [flags]

Runs COMMAND in a running sandbox, on a terminal when yours is one, and exits
with its status. The sandbox keeps running. COMMAND starts in the sandbox
user's home unless --workdir says otherwise.

Examples:

sandbox-cli exec demo -- git clone https://github.com/you/app
sandbox-cli exec demo --workdir /sandbox/home/app -- make test

Flags:

#sandbox-cli gateway

Operate a running gateway's nodes: list, cordon, drain, lost sandboxes, the audit log (admin key).

sandbox-cli gateway [command]

Calls a gateway's admin API with the current context's key, which needs the
admin scope. Upgrading a node is: drain NODE (or cordon it and wait), upgrade
and restart its sandboxd, uncordon NODE. The gateway keeps a node it cordoned
cordoned across the node's restart, until it is uncordoned here.

Subcommands: audit, cordon, drain, lost, nodes, uncordon.

Flags:

#sandbox-cli gateway audit

Show the gateway's audit log: who did what, newest last.

sandbox-cli gateway audit [flags]

Flags:

#sandbox-cli gateway cordon

Stop placing new sandboxes on a node; what runs there carries on.

sandbox-cli gateway cordon NODE

#sandbox-cli gateway drain

Cordon a node and report its sandboxes; with --terminate, end them all.

sandbox-cli gateway drain NODE [flags]

Cordons NODE, so it takes no new sandboxes, and says how many it still runs.
Without --terminate they carry on until they end; run it again to see the
count fall. With --terminate every sandbox on the node is terminated now.

Flags:

#sandbox-cli gateway lost

List sandboxes on nodes that have not answered for longer than the gateway's grace period.

sandbox-cli gateway lost

#sandbox-cli gateway nodes

List the gateway's nodes: health, cordon, sandboxes running, sandboxd version.

sandbox-cli gateway nodes

#sandbox-cli gateway uncordon

Place new sandboxes on a node again.

sandbox-cli gateway uncordon NODE

#sandbox-cli image

Images a sandboxd starts sandboxes from: list, download ahead of use, remove.

sandbox-cli image [command]

A sandboxd pulls an image the first time a sandbox asks for it. These let its
operator do that ahead of time, see what is installed and what uses it, and
remove what nothing does. On Linux an install also builds the image's root
disk, which is most of the first sandbox's wait. The policy's images list, where
there is one, limits what may be installed. Through a gateway they are not
offered: a node's images are its operator's.

Subcommands: ls, pull, rm.

Flags:

#sandbox-cli image ls

List installed images, those installing, and those that failed.

sandbox-cli image ls

#sandbox-cli image pull

Download and install an image ahead of the first sandbox that wants it.

sandbox-cli image pull IMAGE [flags]

Examples:

sandbox-cli image pull ghcr.io/amitgb14/sandbox-desktop:edge
sandbox-cli image pull --no-wait python:3.13-slim

Flags:

#sandbox-cli image rm

Remove installed images nothing uses, and the layers no other image needs.

sandbox-cli image rm IMAGE...

#sandbox-cli job

Run commands and agents on a gateway's fleet, after you have gone: one run or a batch.

sandbox-cli job [command]

A job is a command (or an agent and a prompt) run in a fresh sandbox per run,
by the gateway, with retries, a timeout and a parallelism limit. Its output
and the files it names are kept for a day after it finishes. Gateway only.

Subcommands: cancel, get, ls, output, run.

#sandbox-cli job cancel

Cancel a job: runs not started never are, and running ones' sandboxes are terminated.

sandbox-cli job cancel ID [flags]

Flags:

#sandbox-cli job get

Show a job and each of its runs.

sandbox-cli job get ID [flags]

Flags:

#sandbox-cli job ls

List your jobs, newest first.

sandbox-cli job ls [flags]

Flags:

#sandbox-cli job output

Print what a run kept of its output (stdout, then stderr to stderr); --file prints a kept file.

sandbox-cli job output ID RUN [flags]

Flags:

#sandbox-cli job run

Start a job from a YAML (or JSON) spec; -f - reads it from stdin.

sandbox-cli job run -f JOB.yaml [flags]

The spec's keys are the API's (docs: README, "Agents and jobs on a fleet"):
name, image, command | agent + prompt, prompts (a batch), parallelism,
completions, retries, timeout_secs, env, secrets, network, resources,
from_snapshot, keep: {output, files}, notify. An unknown key is refused.

Examples:

sandbox-cli job run -f job.yaml
sandbox-cli job run -f job.yaml --wait

Flags:

#sandbox-cli kill

Terminate sandboxes, discarding everything in them.

sandbox-cli kill SANDBOX... [flags]

Flags:

#sandbox-cli list

List sandboxes.

sandbox-cli list [flags]

Flags:

#sandbox-cli logs

Print a sandbox process's output from the start, following it until it exits.

sandbox-cli logs SANDBOX [flags]

Flags:

#sandbox-cli org

Organizations on a gateway: create one, switch between yours, manage its members.

sandbox-cli org [command]

An organization is a tenant users create and share on a gateway. What is made
in one — sandboxes, volumes, secrets, jobs, services — is its own, with its own
quota, and nobody outside it can see it. A command acts in the organization
--org names, else SANDBOX_ORG, else the context's (org use), else your key's
own tenant, called "default" when it has no name. Gateway only.

Subcommands: create, ls, members, use.

Examples:

sandbox-cli org create acme
sandbox-cli org use acme
sandbox-cli org members add bob
sandbox-cli --org acme ls

#sandbox-cli org create

Create an organization, with you as its owner (needs the org:create scope).

sandbox-cli org create NAME [flags]

NAME is 1 to 30 lowercase letters, digits and dashes, starting with a letter,
with no "--"; "default" and "admin" are reserved, and a name already used by
a tenant is taken.

Flags:

#sandbox-cli org ls

List the organizations you may act in; * marks the current one.

sandbox-cli org ls [flags]

Flags:

#sandbox-cli org members

List the current organization's members.

sandbox-cli org members [flags]

Subcommands: add, rm.

Flags:

#sandbox-cli org members add

Add a member to the current organization, or change one's role (owners only).

sandbox-cli org members add USER [flags]

USER is named as their API key names them. A user name is unique only within
a tenant, so --tenant says which tenant their keys are in; it defaults to
yours ("default" for keys with none).

Examples:

sandbox-cli org members add bob
sandbox-cli --org acme org members add carol --role owner --tenant team-c

Flags:

#sandbox-cli org members rm

Remove a member from the current organization (owners only); what they had open there ends at once.

sandbox-cli org members rm USER [flags]

Flags:

#sandbox-cli org use

Make NAME the organization this context acts in.

sandbox-cli org use NAME [flags]

Flags:

#sandbox-cli resume

Bring a suspended sandbox back as it was.

sandbox-cli resume SANDBOX [flags]

Flags:

#sandbox-cli run

Run a command in a new sandbox.

sandbox-cli run [flags] -- COMMAND [ARGS...]

Creates a sandbox, runs COMMAND in the sandbox user's home directory on a
terminal (or streamed, when stdin is not one), and removes the sandbox. A
sandbox needs no repository: clone one inside it if the command wants code.

Examples:

sandbox-cli run -- uname -a
sandbox-cli run -- sh -c 'git clone https://github.com/you/app && cd app && make test'
sandbox-cli run --network none -- make
sandbox-cli run --detach -- ./long-job.sh

Flags:

#sandbox-cli secret

Keep values on a gateway for jobs to name: an agent's API key, a registry token.

sandbox-cli secret [command]

A secret is a value your tenant keeps on the gateway, sealed at rest, that a
job sets in its runs' environment by name (secrets: [NAME], or agent-run
--secret NAME). The API never returns a value once it is set. Gateway only.

Subcommands: ls, rm, set.

#sandbox-cli secret ls

List your tenant's secrets by name.

sandbox-cli secret ls [flags]

Flags:

#sandbox-cli secret rm

Remove a secret.

sandbox-cli secret rm NAME [flags]

Flags:

#sandbox-cli secret set

Set a secret, its value read from stdin.

sandbox-cli secret set NAME [flags]

Examples:

sandbox-cli secret set ANTHROPIC_API_KEY < key.txt
printf %s "$TOKEN" | sandbox-cli secret set REGISTRY_TOKEN

Flags:

#sandbox-cli service

Services on a gateway: a sandbox spec and a count the gateway keeps running.

sandbox-cli service [command]

A service is a sandbox spec and a number of replicas a sandbox-gateway keeps
true: it replaces a replica that fails its health check or is lost with its
node, spreads replicas across nodes, rolls a change out one replica at a
time, and routes HTTP to the healthy ones when the service is public.
Services need a gateway; a single sandboxd has none. See docs/services.md.

Subcommands: deploy, get, ls, rm, scale.

Flags:

#sandbox-cli service deploy

Create a service, or update it (a rolling update) if it exists.

sandbox-cli service deploy -f service.yaml [flags]

Flags:

#sandbox-cli service get

Show a service: its spec, its rollout, and each replica's health.

sandbox-cli service get NAME

#sandbox-cli service ls

List services.

sandbox-cli service ls

#sandbox-cli service rm

Delete services and terminate their replicas.

sandbox-cli service rm NAME...

#sandbox-cli service scale

Set how many replicas a service keeps.

sandbox-cli service scale NAME REPLICAS

#sandbox-cli shell

Open an interactive shell in a running sandbox.

sandbox-cli shell SANDBOX [flags]

Starts bash (or sh, where the image has no bash) in a running sandbox, in the
sandbox user's home, and connects your terminal to it. Exiting the shell leaves
the sandbox running. SANDBOX is an id or a name, as `sandbox-cli list` shows.

Examples:

sandbox-cli shell demo
sandbox-cli shell sbx_0123456789abcdef --context box

Flags:

#sandbox-cli snapshot

Capture a sandbox; start forks of it with run --from-snapshot.

sandbox-cli snapshot SANDBOX [flags]

Flags:

#sandbox-cli snapshot-schedule

Snapshot a running sandbox on a schedule, keeping the newest few.

sandbox-cli snapshot-schedule SANDBOX [flags]

Examples:

sandbox-cli snapshot-schedule demo --every 30m --keep 3
sandbox-cli snapshot-schedule demo --off

Flags:

#sandbox-cli ssh

Open an SSH session to a sandbox through a gateway (or a shell over the API on a plain sandboxd).

sandbox-cli ssh [flags] SANDBOX [-- COMMAND [ARGS...]]

Against a gateway, registers your public key if it is not already, pins the
gateway's SSH host key in ~/.config/sandbox/known_hosts, and runs your
ssh client: `ssh -p PORT SANDBOX@HOST`. Afterwards plain ssh works too. With
COMMAND, runs it instead of a login shell. The exit status is ssh's.
Flags go before SANDBOX: everything after it is the command's.

The key is --identity (a .pub file, or a private key with its .pub beside
it), else the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub, id_rsa.pub.
Only the public half is read; ssh does the authentication.

A gateway lets you in only while you hold an active API key with the
sandbox:ssh scope, and closes an open session once you no longer do.

A plain sandboxd has no SSH server: there this opens a shell (or runs
COMMAND) in the sandbox through the API instead, and says so.

Examples:

sandbox-cli ssh demo
sandbox-cli ssh demo -- uname -a
sandbox-cli ssh --identity ~/.ssh/work_ed25519 --context fleet sbx_n1_0123456789abcdef

Flags:

#sandbox-cli ssh-access

Print a short-lived ssh command for one sandbox, needing no registered key.

sandbox-cli ssh-access SANDBOX [flags]

Asks the gateway for a token that logs in to SANDBOX until it expires, and
prints the ssh command that uses it. The token is the SSH user name and the
whole credential: anyone holding the line can log in until it expires, so
hand it only to whoever should have that access. Gateway only.

Examples:

sandbox-cli ssh-access demo
sandbox-cli ssh-access demo --ttl 5m

Flags:

#sandbox-cli ssh-key

Manage the public keys a gateway accepts for SSH logins.

sandbox-cli ssh-key [command]

A gateway's SSH server logs you in with a public key you registered:
`ssh SANDBOX@gateway -p PORT`. These commands add, list and remove yours.
A login needs an active API key with the sandbox:ssh scope, and removing
a key closes the connections made with it.
A plain sandboxd has no SSH server and refuses them.

Subcommands: add, list, rm.

#sandbox-cli ssh-key add

Register a public key (default: ~/.ssh/id_ed25519.pub, id_ecdsa.pub or id_rsa.pub).

sandbox-cli ssh-key add [FILE] [flags]

Examples:

sandbox-cli ssh-key add
sandbox-cli ssh-key add ~/.ssh/work_ed25519.pub --sandbox demo

Flags:

#sandbox-cli ssh-key list

List your registered keys.

sandbox-cli ssh-key list [flags]

Flags:

#sandbox-cli ssh-key rm

Remove a registered key.

sandbox-cli ssh-key rm ID [flags]

Flags:

#sandbox-cli studio

Open Studio: the browser view of your sandboxes.

sandbox-cli studio [flags]

Serves Studio on a loopback port and prints the address to open, which carries a
token made for this launch: anyone else on this machine can reach the port, and
the token is what keeps them out. Studio talks to the sandboxd of the current
context (or --context) and holds its token itself; the browser never sees it.

Ctrl-C stops Studio; sandboxes it started keep running.

Subcommands: host.

Flags:

#sandbox-cli studio host

Serve Studio to many users, each signed in with their own gateway key.

sandbox-cli studio host [flags]

Serves Studio on a public address for the users of a gateway. Each user signs in
once with their own API key, usually by opening an invite link
(https://studio.example.com/#key=sgk_…, printed by sandbox-gateway keys create
--invite-url), and from then on acts as themselves: the gateway decides what
they see, exactly as for their own CLI.

It holds no credential of its own and reads nothing from this machine: no
context, no agent logins, no environment, no config. Unattended agent runs go
through jobs, with the user's API key stored as a secret. Admin keys are refused;
use sandbox-cli studio on your own machine for those.

Sessions are kept in memory: a restart signs everyone out, and they open their
invite link again.

Flags:

#sandbox-cli suspend

Stop a sandbox, keeping its memory, processes and disk.

sandbox-cli suspend SANDBOX [flags]

Flags:

#sandbox-cli template

Sizes a sandbox can be launched at, by name (run --template).

sandbox-cli template [command]

A template is a size — vCPUs, memory and disk — by name: micro, small, medium,
large and xlarge are built in, and Studio's Templates screen saves more, in
~/.config/sandbox/studio.json. Launch at one with `sandbox-cli run --template
NAME` or `sandbox-cli agent <name> --template NAME`; --cpus, --memory and --disk
given beside it win for their own field. sandboxd's limits still apply.

Subcommands: ls.

#sandbox-cli template ls

List the templates: built in, then those saved in Studio.

sandbox-cli template ls

#sandbox-cli tunnel

Forward a local port to a port inside a sandbox.

sandbox-cli tunnel SANDBOX [LOCAL:]PORT [flags]

Examples:

sandbox-cli tunnel sbx_… 3000          # localhost:3000 -> the sandbox's 3000
sandbox-cli tunnel sbx_… 8080:3000

Flags:

#sandbox-cli update

Rename, relabel, retime or change the network of a live sandbox.

sandbox-cli update SANDBOX [flags]

Changes a live sandbox in place; only what a flag names changes.

--label adds or changes a label and --label KEY- (or --unlabel KEY) removes one;
the others are kept. --idle sets how long it may sit idle before it is
terminated (0: never, where the server allows that). --network changes the
network of a running sandbox, as run's flags would set it: --allow adds to the
built-in hosts unless --no-baseline, and an agent's sandbox keeps its agent's
API. Not every endpoint can change a running sandbox's network.

vCPUs and memory are fixed while a VM runs.

Examples:

sandbox-cli update web --name api
sandbox-cli update api --label team=infra --label ticket-
sandbox-cli update api --idle 2h
sandbox-cli update api --network allowlist --allow proxy.golang.org --no-baseline

Flags:

#sandbox-cli version

Print the sandbox-cli version.

sandbox-cli version

#sandbox-cli volume

Named volumes: filesystems that outlive the sandboxes they are mounted in.

sandbox-cli volume [command]

A volume keeps what a sandbox wrote for the next one that mounts it: a package
cache, a dataset, a model's weights. Mount one with
`sandbox-cli run --volume NAME:/path[:ro]`. A volume is mounted in one live
sandbox at a time, never in a system directory.

Subcommands: create, ls, rm.

Flags:

#sandbox-cli volume create

Create an empty volume.

sandbox-cli volume create NAME [flags]

Flags:

#sandbox-cli volume ls

List volumes and where each is mounted.

sandbox-cli volume ls

#sandbox-cli volume rm

Delete volumes and everything on them; refused while mounted.

sandbox-cli volume rm NAME...

#sandbox-cli whoami

Show who the current context's credential is: user, tenant, scopes and key id on a gateway.

sandbox-cli whoami [flags]

Flags: