Verbs

agentproto sandbox

agentproto sandbox list   [--no-probe] [--reconcile] [--json]
agentproto sandbox attach <provider> <sandboxId> [--config-json <json>] [--keep-alive] [--json]
agentproto sandbox rm     <sandboxId|label|id-prefix> [--box] [--yes] [--json]
agentproto sandbox gc     [--apply] [--pause] [--provider <slug>]... [--include-attached] [--json]
agentproto sandbox checkpoint-gc [--repo <dir>] [--dry-run] [--apply] [--json]
agentproto sandbox exec   <provider> [--sandbox-id <id>] [--cwd <dir>] [--timeout <dur>]
                          [--env NAME=value ...] [--env-profile NAME=<profileId> ...]
                          [--file <local>:<boxPath> ...] [--json] -- <command...>
agentproto sandbox egress-health [--provider <slug>] [--model <id>] [--probe <model>]
                                 [--harness <slug>] [--json]

Browse the daemon's sandbox ledger (every box the daemon has booted, reconnected to, or paused — stored in ~/.agentproto/sandboxes.json), and connect to already-existing boxes without tearing them down.

Provider credentials are read from ~/.agentproto/sandbox-creds/<slug>.json (written by the setup_sandbox_provider MCP tool); provider API keys (e.g. BOX_API_KEY, E2B_API_KEY) must additionally be set in this process's own environment.

Subverbs

list

agentproto sandbox list
agentproto sandbox list --json
agentproto sandbox list --no-probe
agentproto sandbox list --json --reconcile

Prints the sandbox ledger — every box the daemon has booted, reconnected to, paused, or stopped — with its current state, idle-expiry, the origin session that spawned it, and, for a shared box, the sessions currently attached to it (ATTACHED column; attachedSessions in --json — the refcount that keeps the box alive while any of them remains).

The table includes a LIVE column showing the result of a per-row provider liveness probe (yes / no / ? probe-errored / — provider can't probe). The LIVE column is the only reliable signal that a box still exists on its provider: the STATE column reflects what the daemon last did and may lag reality (a provider-reaped box still shows paused until probed). Probes are network calls; pass --no-probe to skip them.

This same probe pass is a reconcile: any row the provider confirms gone is flipped to state: "gone" in the ledger (never deleted, and the box itself is never touched — this is read-only against the provider). Table mode reconciles by default; --json does not (a plain --json is a raw, unprobed dump) unless --reconcile is also passed, which forces the same pass and adds a reconciled: {checked,alive,gone,unknown,skipped} summary to the JSON output. The daemon also runs this same reconcile once at boot (best-effort, logged to stderr) so a stale ledger — dozens of paused rows the provider actually reaped long ago — self-heals without anyone running sandbox list first.

FlagDefaultDescription
--no-probefalseSkip the per-row provider liveness probes (no network calls). The LIVE column shows — for every row. Table mode only — --json never probes unless --reconcile is passed.
--reconcilefalseForce the provider-liveness/reconcile pass even under --json (table mode already does this by default), and include the reconciled summary in JSON output.
--jsonfalsePrint the raw { sandboxes: […] } JSON instead of the human table.

rm <sandboxId|label|id-prefix>

agentproto sandbox rm my-task-label
agentproto sandbox rm bx_abc123 --box --yes

Removes the ledger entry for the given box (resolved by exact label, full sandboxId, or unique id prefix). By default the box itself is left running/paused on the provider — only the local bookkeeping row is dropped.

FlagDefaultDescription
--boxfalseALSO stop the box on its provider (destructive — the sandbox and all data inside it is torn down). Without --yes, an interactive terminal is asked to confirm.
--yesfalseSkip the interactive confirmation for --box. Required in non-TTY environments.
--jsonfalsePrint { ok, removed, boxStopped } as JSON.

attach <provider> <sandboxId>

Resumes the sandbox, ensures its agentproto daemon is healthy, and exposes it with a PERSISTENT, token-gated URL (never an ungated one — a provider that can't gate the port fails the command rather than printing an insecure URL). Prints the connection descriptor and a paste-ready .mcp.json snippet.

FlagDefaultDescription
--config-json <json>{}Provider-specific SandboxSpec.config overrides, e.g. '{"port":18790}'.
--keep-alivefalseKeep the sandbox awake indefinitely for an always-on rendezvous.
--jsonfalsePrint only {"descriptor":…,"mcpConfig":…} as JSON.

gc

agentproto sandbox gc              # dry run — print what would be torn down
agentproto sandbox gc --apply      # actually kill orphan boxes on the provider
agentproto sandbox gc --apply --pause   # pause instead of kill (stays reattachable)
agentproto sandbox gc --json       # machine-readable plan / outcomes

Reaps two kinds of orphan boxes:

  1. Ledger orphans — ledger entries whose origin session ended in a failure state (error / killed / exited) — the session can never return to its box, so the box is wasted spend.
  2. Provider-control-plane orphans — running/paused boxes the provider still reports that no live ledger row accounts for, once they are older than a grace window (15 minutes by default). The sweep enumerates each provider's control plane (listBoxes) and deletes those boxes; a box still attached to a live session is left alone unless --include-attached opts it in. Each provider is scanned independently: one provider's failure is reported for that provider and never aborts the others, and a provider that cannot be enumerated (not configured, no control plane, no listBoxes) is reported not scanned — never as "no orphan found".

Dry run by default; nothing is torn down until --apply is passed. The daemon runs a separate periodic sweep for ledger orphans (1 h cadence by default; AGENTPROTO_SANDBOX_GC_INTERVAL_MS overrides or disables it). The provider-control-plane sweep is invoked by the CLI (sandbox gc) and the sandbox_gc MCP tool, not by that daemon timer.

Requires a running daemon to look up origin-session statuses and to resolve provider control planes.

FlagDefaultDescription
--applyfalseActually tear down (or pause) the orphan boxes and stamp their ledger rows stopped. Without this, the command only prints the plan.
--pausefalseWith --apply: pause the boxes instead of killing them, keeping them reattachable via sandbox attach. Note: a paused e2b box still bills, so the default kill is usually preferable for orphans.
--provider <slug>computerRestrict the provider sweep to one provider (repeatable, e.g. --provider computer --provider e2b). Ledger orphans are unaffected.
--include-attachedfalseAlso propose provider-side boxes the provider still counts a session on (attached).
--jsonfalsePrint the plan / outcomes as JSON instead of the human summary.

The MCP twin is the sandbox_gc tool.

checkpoint-gc

agentproto sandbox checkpoint-gc          # dry run — table of every checkpoint ref
agentproto sandbox checkpoint-gc --repo ~/work/repo
agentproto sandbox checkpoint-gc --json   # machine-readable plan
agentproto sandbox checkpoint-gc --apply  # delete every ref listed SAFE

Reaps stale checkpoint branches: every agentproto-checkpoint/<work-branch> ref on the remote that a sandbox session's teardown no longer needs. A box that dies with uncommitted work leaves its snapshot ref behind forever; this command judges each one SAFE when the work it rescued is provably elsewhere:

  • the PR of wt/<slug> is merged or closed on the forge (via the repo's forge client, when credentials resolve one);
  • the snapshot's tree IS the remote wt/<slug> tip's tree or the base branch's tree: the content is already there verbatim;
  • (clean snapshots only) the snapshot's parent commit is merged into base or the work branch, squash-merged (git merge-tree --write-tree yields exactly the base tree), or patch-merged (git cherry maps every commit onto an applied patch id).

A snapshot whose tree differs from its parent's carries uncommitted delta; deleting it can lose that work, so only the PR and tree tiers can mark those SAFE. Anything else comes back keep and stays on the remote.

FlagDefaultDescription
--repo <dir>cwdRepo to run in; the remote acted on is its origin.
--dry-runonTable or --json plan; nothing is deleted. Mutually exclusive with --apply.
--applyfalseDelete every ref classified SAFE. Each delete is preceded by a FRESH re-plan, so a stale plan never deletes a ref whose classification changed.
--jsonfalsePrint the plan ({ refs: [...] }) or the apply outcomes as JSON.

The daemon also runs this same classification best-effort when a sandboxed session exits: that session's OWN ref is deleted once it is superseded (logged on failure, never blocking teardown). This command remains the manual, repo-wide tool.

exec <provider>

# Secret from an auth profile — the daemon reads it, you never hold it
agentproto sandbox exec e2b --env-profile OPENAI_API_KEY=openai-main -- python run.py

# Reuse an existing box, upload a script instead of inlining it
agentproto sandbox exec e2b --sandbox-id sbx_abc \
  --file ./job.sh:/home/user/job.sh --cwd /home/user --timeout 10m -- bash job.sh

# Machine-readable
agentproto sandbox exec e2b --json -- 'uname -a && id'

Runs one command inside a sandbox — the CLI twin of the sandbox_exec MCP tool. It talks to the running daemon (POST /sandboxes/exec, token-gated like every mutating route) so --env-profile resolves against the daemon's keychain and auth profiles; the secret value never reaches the CLI process, its argv, or its output.

Everything after -- is the command. One argument is passed verbatim (so -- 'a && b' is a shell snippet); several arguments are shell-quoted and joined. Without --sandbox-id an ephemeral box is booted for the command and always torn down afterwards; with it, the existing box is reused and left as found.

Exit code = the box command's exit code (0-255). A failure that never produced one — no live daemon, rejected input, unknown/disabled profile, provider error — exits 125 with the reason on stderr (--json still prints the daemon's {ok:false, code, message} body); usage errors exit 2. The two overlap if the box command itself exits 125 — read --json to tell them apart.

FlagDefaultDescription
--sandbox-id <id>ephemeralRun against this existing box.
--cwd <dir>provider defaultAbsolute working directory inside the box.
--timeout <dur>nonePer-command wall clock (500ms, 30s, 10m, 2h; a bare integer is ms, and <1000 is rejected as a likely units slip).
--env NAME=value—Literal env var for this command; repeatable. Don't put secrets here: the value sits in your shell history and ps.
--env-profile NAME=<profileId>—Set NAME from the stored credential of auth profile <profileId> (list ids with the auth_profile_list MCP tool); repeatable. Names a profile, never a keychain ref. Sub-account (source-backed) profiles resolve through their SubaccountProvider. Unknown or disabled profiles, invalid names, and a NAME also given via --env are rejected before anything boots. Not supported on device: targets. Resolved values are redacted from stdout, stderr and errors (<redacted>).
--file <local>:<boxPath>—Upload a local file to the absolute <boxPath> before the command runs; repeatable. Needs a provider whose boxes can write files (e2b today).
--jsonfalsePrint the daemon's response as JSON instead of streaming stdout/stderr.

Limits: a command over 16 KB or an env over 32 KB (literal + profile values) is rejected with an actionable error — upload the script with --file and run it by path. Provider errors never echo the full command: it is cut to ~200 characters with a …(N chars) marker.

egress-health

agentproto sandbox egress-health                        # the pool + active cooldowns
agentproto sandbox egress-health --model opencode/big-pickle
agentproto sandbox egress-health --probe opencode/big-pickle --harness opencode

Shows the provider's egress address pool (slot, public IP, boxes in use) and the active per-IP model cooldowns, through the running daemon (GET /sandboxes/egress-health). A free-tier model cap is enforced per source IP, so a slot cooling down for a model is skipped when a box boots with egressIp: auto. Cooldowns are set by a failed preflight or a usage/rate-limit turn on a box, and expire on their own.

--probe <model> re-probes on demand: it boots one box per pool slot, runs the model-answers preflight for <model> from each address (POST /sandboxes/egress-health/probe), and clears or sets that address's cooldown. There is no automatic schedule — run it when you suspect the pool. Requires a running daemon.

FlagDefaultDescription
--provider <slug>computerProvider whose pool to show (or probe).
--model <id>—Narrow the cooldown list to one model. Mutually exclusive with --probe.
--probe <model>offRe-probe every slot from each address; on demand only.
--harness <slug>opencodeHarness the probe runs; only accepted with --probe. --adapter is a deprecated alias of --harness: it still works and prints a deprecation line on stderr.
--jsonfalsePrint the daemon's response as JSON instead of the human table.

Exit codes: 0 healthy; 1 when a probe returns a ko/error verdict; 125 for infrastructure failures (no daemon, rejected request — same as exec); 2 for usage errors.

The always-on model (--keep-alive)

--keep-alive is for a sandbox meant to stay reachable indefinitely rather than get reclaimed by the provider's own idle/TTL auto-stop. The documented Box mechanism for "runs until you stop it" is no-auto-stop (box extend <id> --no-auto-stop / ttlSeconds: null), and it's sticky across resume — so --keep-alive (re-)asserts it on connect(), defensively, even for a box that already defaults to it (e.g. one created before that default, or with an explicit numeric ttlSeconds). It does not start a background heartbeat process — a one-shot CLI invocation can't cleanly host one, and no-auto-stop has no deadline to begin with, so none is needed. --keep-alive is a no-op for providers with no equivalent concept (e.g. e2b).

Examples

# Browse all boxes the daemon has touched (with liveness probes)
agentproto sandbox list
agentproto sandbox list --json

# Browse without network calls (skip liveness probes)
agentproto sandbox list --no-probe

# Remove a ledger entry (box stays running/paused on the provider)
agentproto sandbox rm my-task-label
agentproto sandbox rm bx_abc123

# Remove ledger entry AND stop the box (destructive)
agentproto sandbox rm bx_abc123 --box --yes

# Dry-run GC — see which orphan boxes would be reaped
agentproto sandbox gc

# Actually reap orphan boxes (sessions that errored/were killed)
agentproto sandbox gc --apply

# Attach to a Box sandbox booted by an earlier agent_start sandbox spawn
agentproto sandbox attach box bx_abc123

# Pin it awake indefinitely for an always-on rendezvous
agentproto sandbox attach box bx_abc123 --keep-alive

# Same, machine-readable
agentproto sandbox attach e2b sbx_abc123 --json

# Override the port the daemon listens on inside the box
agentproto sandbox attach box bx_abc123 --config-json '{"port":19000}'

# Run a command in a fresh box with a secret taken from an auth profile
agentproto sandbox exec e2b --env-profile OPENAI_API_KEY=openai-main -- python run.py

# Check the egress pool and its active per-model cooldowns
agentproto sandbox egress-health --model opencode/big-pickle

Non-JSON output:

sandbox attached  provider=box  sandboxId=bx_abc123
  mcpUrl      https://frazil-pneuma-rallye-18790.on.ascii.dev/mcp
  token       •••••••• (gated)
  allowOrigin https://frazil-pneuma-rallye-18790.on.ascii.dev
  keepAlive   no

Paste into .mcp.json:
{
  "mcpServers": {
    "sandbox-box-bx_abc123": {
      "type": "http",
      "url": "https://frazil-pneuma-rallye-18790.on.ascii.dev/mcp",
      "headers": { "Cookie": "_port_auth=••••••••" }
    }
  }
}

The exact auth header is provider-specific and comes straight from the descriptor's authHeaders. Box gates its private hostname on a Cookie: _port_auth=<token> (its port edge ignores Authorization: Bearer); a token-only provider falls back to Authorization: Bearer <token>.

See also

  • sessions.md — agent_start.sandbox / sessions start --sandbox boots and drives a fresh sandbox; sandbox list/attach/rm operate on already-existing boxes
  • auth.md — credential storage conventions