#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 [flags]

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

On a gateway that keeps agent logins, an agent run uses the login the gateway
keeps for you, and GATEWAY says whether there is one; THIS MACHINE is the login
saved here, which a first run gives a gateway that keeps none yet. Elsewhere
the login is this machine's alone.

Flags:

#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 api-key

Make, list and revoke your own API keys on a gateway, for your programs to act as you.

sandbox-cli api-key [command]

A personal API key acts as you, for a program: a CI job, a script, the CLI on
another machine. It has the scopes you give it, from your own (never admin),
and always expires: in an hour to 366 days, never after the key or account
you make it with. Your policy applies to it. Revoking, suspending or expiring
your account ends it. A personal key cannot make or revoke keys itself.
Gateway only.

Subcommands: create, list, revoke.

#sandbox-cli api-key create

Make a key; its secret is printed once, or written to --out.

sandbox-cli api-key create NAME [flags]

Examples:

sandbox-cli api-key create ci --scope sandbox:read --scope sandbox:create --expires 90d
sandbox-cli api-key create laptop --scope sandbox:read --out ~/.config/sandbox/laptop.key

Flags:

#sandbox-cli api-key list

List your personal keys (never their secrets).

sandbox-cli api-key list [flags]

Flags:

#sandbox-cli api-key revoke

Revoke one of your personal keys; whatever uses it is refused at once.

sandbox-cli api-key revoke ID [flags]

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: its nodes, users' keys and policies, 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, egress-groups, images, invites, keys, lost, nodes, policies, 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 egress-groups

Set, list and remove allowlist groups (set and remove: admin key).

sandbox-cli gateway egress-groups [command]

An allowlist group is a named set of hosts, kept by an admin, that any user
adds to a sandbox's allowlist by name (run --allow-group, update --allow-group,
or Studio's Network step) instead of listing the hosts. The gateway turns the
name into hosts; each node's policy still decides which hosts it allows. A
change holds for sandboxes created after it; running ones keep their hosts.
A group a running job or a service names cannot be removed.

Subcommands: list, remove, set.

Examples:

sandbox-cli gateway egress-groups set go --host proxy.golang.org --host sum.golang.org
sandbox-cli gateway egress-groups list
sandbox-cli run --network allowlist --allow-group go -- go build ./...

#sandbox-cli gateway egress-groups list

List the groups any user may name.

sandbox-cli gateway egress-groups list

#sandbox-cli gateway egress-groups remove

Remove a group no running job or service names.

sandbox-cli gateway egress-groups remove NAME

#sandbox-cli gateway egress-groups set

Create or replace a group; a change holds for sandboxes created after it.

sandbox-cli gateway egress-groups set NAME [flags]

Flags:

#sandbox-cli gateway images

Images on the gateway's nodes: list, download ahead of use, remove (admin key).

sandbox-cli gateway images [command]

The images the gateway's nodes start sandboxes from, once for the fleet. A pull
goes to every node that takes new sandboxes (healthy, not cordoned), each as
its own policy allows. A removal is refused, removing nothing, while any node
still needs the image (a sandbox starts from it, or it is the node's default
or pooled image), and then takes it from every node that has it.

Subcommands: ls, pull, rm.

Examples:

sandbox-cli gateway images pull ghcr.io/amitgb14/sandbox-desktop:edge
sandbox-cli gateway images ls
sandbox-cli gateway images rm python:3.13-slim

#sandbox-cli gateway images ls

List the nodes' images, and which nodes have each.

sandbox-cli gateway images ls

#sandbox-cli gateway images pull

Have every node that takes new sandboxes download and install an image.

sandbox-cli gateway images pull IMAGE

#sandbox-cli gateway images rm

Remove images from every node, where no node still needs them.

sandbox-cli gateway images rm IMAGE...

#sandbox-cli gateway invites

Invite people by email to sign in to hosted Studio with a password (admin key).

sandbox-cli gateway invites [command]

An invite is a one-time link for an email address. Opening it in hosted Studio,
the person chooses a password and becomes an account: a user with the tenant,
scopes, policy and lifetime the invite names, as a key issued with them would
have. They sign in with the address and password from then on; the account is
listed, renewed and revoked with gateway keys.

With no --tenant the invite is a sign-up: the account gets an organization of
its own, named after the user (john.smith gets john-smith), and the invite is
refused if that name is in use. --tenant puts it in an existing one, default
for the default tenant.

Subcommands: create, list, resend, revoke.

#sandbox-cli gateway invites create

Make an invite; its link is printed once.

sandbox-cli gateway invites create [flags]

Examples:

# a demo user: 30-minute sandboxes, an account for a week, the link emailed
sandbox-cli gateway invites create --email bob@example.com --user bob \
  --scope sandbox:read --scope sandbox:create --scope sandbox:delete \
  --policy demo --expires 7d --send --invite-url https://studio.example.com

Flags:

#sandbox-cli gateway invites list

List invites not yet used.

sandbox-cli gateway invites list

#sandbox-cli gateway invites resend

Make a pending invite's link again, valid two days; the old link stops working.

sandbox-cli gateway invites resend ID [flags]

Examples:

sandbox-cli gateway invites resend inv_0123456789abcdef --send
sandbox-cli gateway invites resend inv_0123456789abcdef --invite-url https://studio.example.com

Flags:

#sandbox-cli gateway invites revoke

Withdraw an invite; its link stops working.

sandbox-cli gateway invites revoke ID

#sandbox-cli gateway keys

Issue, list and revoke the gateway's API keys (admin key).

sandbox-cli gateway keys [command]

Subcommands: create, list, renew, reset, restore, revoke, suspend.

#sandbox-cli gateway keys create

Issue an API key; its secret is printed once.

sandbox-cli gateway keys create [flags]

Issues an API key: a user, in a tenant, with scopes. A demo user is one with a
policy (gateway policies) and an expiry; a long-time user has neither. With
--invite-url it also prints the link that signs the user in to hosted Studio.

Examples:

# a demo user: 30-minute sandboxes, for a week
sandbox-cli gateway keys create --user bob --tenant bob \
  --scope sandbox:read --scope sandbox:create --scope sandbox:delete \
  --policy demo --expires 7d --invite-url https://studio.example.com
# a long-time user
sandbox-cli gateway keys create --user carol --tenant carol \
  --scope sandbox:read --scope sandbox:create --scope sandbox:delete --scope sandbox:ssh

Flags:

#sandbox-cli gateway keys list

List API keys (never their secrets).

sandbox-cli gateway keys list

#sandbox-cli gateway keys renew

Change when an API key stops working: --expires 30d, never, or now.

sandbox-cli gateway keys renew ID [flags]

Examples:

sandbox-cli gateway keys renew key_0123456789abcdef --expires 30d
sandbox-cli gateway keys renew key_0123456789abcdef --expires now

Flags:

#sandbox-cli gateway keys reset

Make a link that sets a new password for an account.

sandbox-cli gateway keys reset ID [flags]

Makes a one-time link, valid two days, with which the account's user sets a new
password; their sign-ins end when it is used. The old password works until then.

Examples:

sandbox-cli gateway keys reset key_0123456789abcdef --invite-url https://studio.example.com

Flags:

#sandbox-cli gateway keys restore

Take back a suspension that has not run out.

sandbox-cli gateway keys restore ID

#sandbox-cli gateway keys revoke

Revoke an API key; what it has open is closed at once.

sandbox-cli gateway keys revoke ID

#sandbox-cli gateway keys suspend

Revoke a key restorably: refused at once, revoked for good in an hour.

sandbox-cli gateway keys suspend ID

The key is refused from now on, as a revoked one is, and what it has open is closed;
its sign-ins end and its jobs are cancelled. For an hour, gateway keys restore ID takes
it back; after that it is revoked for good.

#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 policies

Set, list, assign and remove user policies (admin key).

sandbox-cli gateway policies [command]

A user policy holds a user's sandboxes to limits on top of the nodes' own; for
now, how long each may exist. A sandbox asking for no lifetime gets the
policy's, and one asking for more is refused. A change to a policy holds for
sandboxes created after it; move a running one's end with
sandbox-cli update SANDBOX --lifetime +15m. Admin keys are held to none.

Subcommands: assign, list, remove, set.

Examples:

sandbox-cli gateway policies set demo --max-lifetime 30m
sandbox-cli gateway policies assign bob demo --tenant bob
sandbox-cli gateway policies assign bob --tenant bob --none

#sandbox-cli gateway policies assign

Give a user a policy, or none with --none.

sandbox-cli gateway policies assign USER [POLICY] [flags]

Flags:

#sandbox-cli gateway policies list

List policies and the users holding each.

sandbox-cli gateway policies list

#sandbox-cli gateway policies remove

Remove a policy no user holds.

sandbox-cli gateway policies remove NAME

#sandbox-cli gateway policies set

Create or change a policy; a change holds for sandboxes created after it.

sandbox-cli gateway policies set NAME [flags]

Flags:

#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 these are not
offered; its admin manages the nodes' images with sandbox-cli gateway images.

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, labels, 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 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. The case is kept as typed and ignored when matching: Acme-Labs and
acme-labs are one organization, whose tenant is acme-labs.

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 registry

Keep your organization's logins for private image registries on a gateway.

sandbox-cli registry [command]

A registry login is a user name and token your organization keeps on the
gateway, sealed at rest. Every sandbox, job and service of the organization
whose image is on that registry is pulled with it; no other organization's
is. The token is never returned once it is set. Gateway only.

Subcommands: login, logout, ls.

#sandbox-cli registry login

Set the login for a registry, its token read from stdin.

sandbox-cli registry login REGISTRY [flags]

Examples:

sandbox-cli registry login ghcr.io --username alice < token.txt
printf %s "$GHCR_TOKEN" | sandbox-cli registry login ghcr.io -u alice

Flags:

#sandbox-cli registry logout

Remove the login for a registry.

sandbox-cli registry logout REGISTRY [flags]

Flags:

#sandbox-cli registry ls

List your organization's registry logins.

sandbox-cli registry ls [flags]

Flags:

#sandbox-cli resize

Give a running sandbox more or fewer CPUs and memory, or a larger disk.

sandbox-cli resize SANDBOX [flags]

A disk that only grows is grown live where the endpoint can: the sandbox and
its processes keep running. New CPUs or memory restart the sandbox at its new
size, in a few seconds: it keeps its id, its network, its files and its
volumes; its processes end, so that is refused while any run. A size left out
is kept. A disk only grows. Through a gateway what it adds counts against your
quota, and the sandbox's node must have the room.

Examples:

sandbox-cli resize my-box --cpus 4 --memory 8192
sandbox-cli resize my-box --disk 20480

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 (secrets: [NAME], or agent-run --secret NAME).
A secret's name need not be the variable it fills: VAR=NAME sets secret NAME as
VAR, so openai-prod and openai-staging can each be OPENAI_API_KEY. 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
sandbox-cli secret set openai-prod < prod.txt   # then --secret OPENAI_API_KEY=openai-prod

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, redeploy, 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 redeploy

Replace a service's replicas, one at a time, with its spec as it is.

sandbox-cli service redeploy NAME

A new revision of the spec the service has, rolled out one replica at a time as an
update is. For what changed outside the spec, which only a new sandbox picks up:
a secret set again, an image tag that now names another image.

#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-ls

List snapshots, newest first.

sandbox-cli snapshot-ls [flags]

Flags:

#sandbox-cli snapshot-rm

Delete snapshots; sandboxes already started from them keep running.

sandbox-cli snapshot-rm SNAPSHOT... [flags]

Examples:

sandbox-cli snapshot-rm snp_0f80da1e250655e9
sandbox-cli snapshot-ls

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 unless --allow-admin: then an admin signs in the same way,
gets the admin screens (users and keys, policies, nodes, audit), and their
session ends after an hour unused or twelve hours in all.

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

--agent-log FILE records what each user's agentos sessions do (prompts, tool
calls, answers) on this machine; without it nothing is kept.

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), and --on-idle suspend has
it suspended instead, to be resumed by the next command, file or shell that
uses it. --lifetime sets when it
ends, busy or not, counted from its creation: 45m sets it, +15m pushes its end
out and -10m brings it nearer. Through a gateway only an admin can push it out.

--network changes the network of a running sandbox, as run's flags would set
it: --allow and --allow-group add 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.

--metrics-export sets where the sandbox's usage is pushed, replacing what was
set, headers included; --metrics-export none stops it.

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 --idle 30m --on-idle suspend
sandbox-cli update api --lifetime +15m
OTEL_AUTH='Bearer …' sandbox-cli update api --metrics-export https://otlp.example.com --metrics-export-header Authorization=OTEL_AUTH
sandbox-cli update api --network allowlist --allow proxy.golang.org --no-baseline
sandbox-cli update api --network allowlist --allow-group go   # through a gateway

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: