Commands

This page lists every agents-sandbox subcommand, alias, and flag. Deprecated flags, config keys, and environment variables are listed in Deprecations.

The commands are grouped by area; jump to a group:

Runtime: run, shell, stop, kill, list, tree, doctor, version, upgrade, completion
Build and images: build, image
Pruning: prune, prune --purge, image prune, volume prune, sandbox prune, sandbox compact
Storage: df, storage
State: state repair
Configuration: config, config paths
Agents: config agent, config home
Volumes: volume
Sandboxes: sandbox

Global flags

These flags are available on every command.

Flag	Short	Default	Purpose
`--yes`	`-y`	`false`	Assume yes to all prompts; authorizes destructive commands non-interactively
`--quiet`	`-q`	`false`	On list commands, print identifiers only; otherwise suppress stdout output
`--log-level`	`-l`	`info`	Minimum log level to show (`error`, `warning`, `info`, `verbose`)

Commands

run

Run a coding agent in a microsandbox VM. This is the default command — agents-sandbox with no subcommand is equivalent to agents-sandbox run.

agents-sandbox [ARGS...]                          # default: run the configured agent
agents-sandbox -w bugfix-fix-thing [ARGS...]            # worktree session
agents-sandbox --dry-run                          # read-only preview
agents-sandbox -m 8G -c 4 -- -c "fix bug"         # CPU/memory + ops
agents-sandbox -- -c "fix bug"                    # arguments to the agent

Arguments after -- are forwarded to the agent. Arguments before -- that don’t match flags are also forwarded.

Flags:

Flag	Short	Default	Purpose
`--worktree`	`-w`	`""`	Isolated agent worktree named , optionally starting from base ref :
`--rebuild`	`-r`	`false`	Rebuild runner image before starting (clean rebuild that pulls the latest base image; still offers an agent upgrade if one is available)
`--no-rebuild`	—	`false`	Reuse the existing runner image even if its inputs changed, and skip the agent upgrade check. A missing image is still built. Can’t be combined with `--rebuild` or `--agent-version`. See Runner Image
`--agent-version`	—	`""`	Pin the version agents-sandbox installs into the runner image (default: latest). Ignored for a user-provided agent.
`--dry-run`	`-n`	`false`	Read-only preview of a run: report the agent version (or that it resolves at build time), whether the runner image would build (with the reasons a real build logs) or be reused, and whether the home volume would be created or reused — without building, creating a volume, writing state, starting a VM, attaching, or making any network request. It also installs no microsandbox runtime, so a fresh host gets the plan without the download. When the reported version is a known, non-pinned one, its line notes `(upgrade check not run)`
`--cpus`	`-c`	`0`	vCPUs for the sandbox (0 = all)
`--memory`	`-m`	`4G`	Memory limit, e.g. `4G`, `512M`
`--disk-size`	—	`""`	Project VM root disk size (e.g. 16G). Empty = microsandbox runtime default (~4 GiB). A larger value grows the root disk live; a smaller one rebuilds the VM. An invalid value is rejected with an error.
`--tmp-size`	—	`""`	Size of `/tmp` tmpfs in the sandbox; unset defaults to `min(2G, memory/2)`. An invalid value, or one at least the memory limit, is rejected with an error.
`--workspace-quota`	—	`16G`	Guest-write quota for the `/workspace` bind mount (e.g. `32G`), bounding writes on top of the host repo. Applied at VM creation; a change triggers recreation. An invalid value is rejected with an error.
`--dry-run-vm`	—	`false`	Skip the VM lifecycle but prepare everything else. A project without a home volume gets none: creating it needs a VM, so the first run with a VM creates it.
`--serve-only`	`-s`	`false`	Start the agent server published on host loopback at a dynamically allocated host port (no in-VM TUI); press `Ctrl-D` to exit, or send `SIGINT`/`SIGTERM` when stdin is not a terminal. The printed `http://127.0.0.1:<port>` URL is authoritative — use it (rather than assuming a fixed port) to connect from clients like Opencode Desktop. Set `OPENCODE_SERVER_PASSWORD` for basic auth (opencode); opencode2’s server requires the baked credential `opencode:opencode` (username:password).
`--port`	`-p`	`[]`	Publish a VM port on the host loopback: `<port>` or `<host>:<guest>` (TCP only, e.g. `3000` or `8080:3000`); comma-separated or repeated. Opt-in — no ports are published by default. Applied at VM creation; a change triggers recreation. Also settable via the `ports:` config key and `AGENTS_SANDBOX_PORTS`. See Networking.
`--agent`	—	`opencode2`	Coding-agent profile to run: `opencode`, `opencode2` (default), `pi`, `claude-code`, `codex`, `hermes`, or `oh-my-pi`.
`--notify`	—	`off`	Notify on session status: `on`, `off`, `desktop`, or `audio` (both `--notify <mode>` and `--notify=<mode>` work; bare `--notify` = `on`). Overridable via `AGENTS_SANDBOX_NOTIFY`. Only applies to the `opencode` and `opencode2` agents (the only agents with a session event stream).
`--open-links`	—	`true`	Open links from the VM (`xdg-open`) in the host’s browser; `--open-links false` or `--open-links=false` turns it off. Overridable via `AGENTS_SANDBOX_OPEN_LINKS`. See Opening links.
`--docker`	—	`false`	Bake the Docker engine into the runner image; overrides the project Dockerfile’s declaration in both directions (`--dind` is a deprecated alias)

Aliases: sandbox run

shell

Start a sandbox VM and open an interactive shell. Useful for debugging the sandbox environment. Shares the common run/shell flags with run.

With --dry-run, shell builds no image, creates no volume, writes no state, starts no VM, and makes no network request. Like run, it skips the prerequisite check (doctor) on a preview, so it installs nothing.

agents-sandbox shell
agents-sandbox shell -w bugfix-fix-thing

Flags:

Flag	Short	Default	Purpose
`--root`	—	`false`	Attach the shell as root (debug/maintenance). Only available on shell.
`--docker`	—	`false`	Bake the Docker engine into the runner image; overrides the project Dockerfile’s declaration in both directions (`--dind` is a deprecated alias)

Aliases: sh, sandbox shell

build

Build or rebuild the runner Docker image. If .agents-sandbox/Dockerfile exists in the project directory, it’s layered on top of the base image. In a bare checkout the project directory is the bare root next to .git, so the Dockerfile is read from there; a worktree-level .agents-sandbox/ is ignored, with a warning. The Docker engine is included when the project Dockerfile declares it — a final-stage # agents-sandbox:docker marker or a runner-base-docker/runner-base-dind base — or when explicit docker config, --docker, or AGENTS_SANDBOX_DOCKER asks for it. Explicit config overrides the Dockerfile declaration in both directions, so docker: false turns the engine off even for a Dockerfile that asks for it. The precedence is explicit config > Dockerfile content > off. See Runner Image.

agents-sandbox build        # build or update if needed
agents-sandbox build -r     # force clean rebuild
agents-sandbox build --agent-version 0.5.0  # pin a specific agent version

Flags:

Flag	Short	Default	Purpose
`--rebuild`	`-r`	`false`	Force a clean rebuild that pulls the latest base image
`--dry-run`	`-n`	`false`	Dry run without building or installing the microsandbox runtime
`--agent`	—	`opencode2`	Coding-agent profile to build: `opencode`, `opencode2` (default), `pi`, `claude-code`, `codex`, `hermes`, or `oh-my-pi`.
`--agent-version`	—	`""`	Pin the version agents-sandbox installs into the image (default: latest). Ignored for a user-provided agent
`--docker`	—	`false`	Bake the Docker engine into the runner image; overrides the project Dockerfile’s declaration in both directions (`--dind` is a deprecated alias)

The version flag does not replace an agent already supplied by a custom base or project Dockerfile.

Aliases: image build

build dockerfile

Print the runner Dockerfile exactly as it would be built for the current project, without invoking docker. The output reflects the selected agent profile and the docker setting, and layers the project’s .agents-sandbox/Dockerfile (if any) on top of the base image. The docker setting follows the same precedence as build (explicit config > Dockerfile content > off). Diagnostics — a legacy or near-miss marker, an ignored earlier-stage marker, or a config override of a Dockerfile signal — are printed to stderr, so stdout stays a clean, pasteable Dockerfile. In a bare checkout the project Dockerfile is read from the bare root next to .git, not the launched worktree.

agents-sandbox build dockerfile            # default agent, no docker
agents-sandbox build dockerfile --docker   # with the Docker engine block
agents-sandbox build dockerfile --agent claude-code

Flags:

Flag	Short	Default	Purpose
`--agent`	—	`opencode2`	Coding-agent profile to build: `opencode`, `opencode2`, `pi`, `claude-code`, `codex`, `hermes`, or `oh-my-pi`.
`--agent-version`	—	`""`	Pin the agent version rendered into the preview (default: no pinned default)
`--docker`	—	`false`	Bake the Docker engine into the runner image; overrides the project Dockerfile’s declaration in both directions (`--dind` is a deprecated alias)

Aliases: image build dockerfile

stop

Gracefully stop the project VM. State remains for future reuse.

With --force, also remove the VM’s persisted state. A VM that is already stopped — or that never fully started — is not stopped again, only removed.

agents-sandbox stop
agents-sandbox stop -f     # stop and remove VM state (also a stopped or never-started VM)

Aliases: sandbox stop

Flags:

Flag	Short	Default	Purpose
`--force`	`-f`	`false`	Remove VM’s persisted state, also for a stopped or never-started VM
`--dry-run`	`-n`	`false`	Show what would be stopped without stopping
`--agent`	—	`opencode2`	Coding-agent profile to stop

kill

Force-kill the project VM. Equivalent to powering off. State may be corrupted.

With --force, also remove the VM’s persisted state. A VM that is already inactive — stopped, or never fully started — is not killed again, only removed.

agents-sandbox kill
agents-sandbox kill -f     # kill and remove VM state (also a stopped or never-started VM)

Aliases: sandbox kill

Flags:

Flag	Short	Default	Purpose
`--force`	`-f`	`false`	Remove VM’s persisted state, also for a stopped or never-started VM
`--dry-run`	`-n`	`false`	Show what would be killed without killing
`--agent`	—	`opencode2`	Coding-agent profile to kill

prune

Prune stale VMs, runner images, dangling Docker images, unused runtime RAM, and stale internal state in one pass. Staleness is determined by age — resources older than the threshold are pruned. Batch prune is the safe tier: it never removes a home volume or the state that points at a surviving one, so prune --yes can never destroy agent state. To prune a single artifact type, use the image prune, volume prune, or sandbox prune subcommands.

Instead of deleting a project that is gone, batch prune lists retired projects — projects with no kept sandbox whose most recent activity is older than the threshold — and points at prune --purge to remove one. The candidates come from every artifact the launcher can still observe (state directories, home volumes, runner images, sandboxes, and root-state adoption claims), so a project whose state directory was deleted by hand still surfaces through its leftover volume. Attribution follows ownership: a volume is credited to the state keys that reference it, so a legacy-named volume a checkout adopted is listed under that checkout, not the ownerless legacy slug. The list is read-only: batch prune never deletes a retired project or its volume.

The summary line reads Pruned N VMs, N home volumes, N docker images, N msb images; the home-volume count is always 0 here. When the runtime reclaims runtime RAM or reports native image-prune data, following runtime memory: and image data: lines carry the file and byte counts, and a line reports reclaimed internal state (unheld claims, stale client leases, state files that recorded no home volume, and emptied state subtrees) when any was swept. A byte count the runtime cannot measure renders as unknown (-), never 0.

The runtime-memory phase reclaims the published branch/snapshot memory backings that no live VM holds, gated by the same --older-than threshold, and honors --dry-run through the runtime’s own preview. The runtime’s age filter is in whole seconds, so a subsecond --older-than (for example 500ms) rounds up to one second rather than collapsing to no filter.

Unless --dry-run is set, prune asks for confirmation before removing anything (defaulting to no). Pass the global --yes to skip the prompt; non-interactively, --yes is required or the command fails fast instead of blocking. --dry-run only previews and never prompts. --older-than rejects a non-positive value.

agents-sandbox prune                       # use --older-than, else manual-prune-age from config, else 7d
agents-sandbox prune --older-than 24h      # 24-hour threshold
agents-sandbox prune --yes                 # skip the confirmation prompt
agents-sandbox prune --dry-run             # preview only (no prompt)
agents-sandbox prune --format json         # machine-readable report on stdout
agents-sandbox prune --purge               # purge the current checkout's project

Flags:

Flag	Short	Default	Purpose
`--older-than`	—	`config`	Prune threshold. Falls back to `manual-prune-age` from config, then to `7d` (e.g. `24h`, `7d`). Rejects a non-positive value.
`--age`	`-a`	—	Deprecated alias for `--older-than`. Hidden; still honored but warns. Setting both is an error.
`--dry-run`	`-n`	`false`	Preview what would be pruned (no confirmation)
`--format`	—	`""`	Output format. `json` prints a structured report on stdout.
`--purge`	—	—	Purge one project instead of pruning (see `prune --purge`). Optional value or positional target.
`--force`	`-f`	`false`	With `--purge`, purge even when a sandbox is running (stopping it first). Ignored without `--purge`.

prune –purge

Remove one project’s artifacts — its sandboxes (a running one stopped first), home volumes, runner images, state files, claims, and root-state adoption claims — in an order that never orphans a volume or drops the last pointer to one. A volume is removed only when the target owns it — by its name, by a state key the target covers, or by an adoption claim the target’s checkout holds — so purging a legacy slug never deletes a saved home a different checkout adopted, and purging that checkout reclaims the legacy-named volume its state points at. A volume that fails to remove keeps its state file, so the pointer to it survives. The age gate does not apply: naming the project is the intent.

<target> is a project slug (whole project) or a <slug>-<agent> key (one agent); omit it to purge the current checkout (an error outside one). A running sandbox fails fast; pass --force to stop it first. The plan is named, then confirmed once. --yes skips the prompt, --dry-run prints the plan without deleting, and --format json prints it as structured output.

agents-sandbox prune --purge                                # purge the current checkout
agents-sandbox prune --purge myproj-1mjusbm3wikhb0          # whole project
agents-sandbox prune --purge myproj-1mjusbm3wikhb0-opencode # one agent key
agents-sandbox prune --purge --dry-run                      # preview the plan
agents-sandbox prune --purge --yes                          # skip the confirmation
agents-sandbox prune --purge --force                        # stop a running sandbox first

--purge shares one engine with sandbox remove --purge.

image prune

Prune cached runner images. Images of stale projects (older than the threshold) are removed entirely; for projects with a surviving VM, the runner-image variants used within the threshold and any image a kept VM currently references are retained, while older variants and surplus digest refs are removed. Ownership follows image list and image remove: a reference whose parsed slug does not embed the launcher’s 14-character hash — a manually loaded single-segment image, or a registry image — is left untouched. Native microsandbox image pruning also reclaims unreferenced manifests and layers left behind by refreshing an image while an older VM still points at the previous manifest. Its report is surfaced: N skipped (in use) counts the image data retained because a live sandbox holds it, and the reclaimed byte count renders as - when the runtime cannot measure it. An msb image’s stale_for_seconds detail is filled from its last use (falling back to its creation time), not always 0.

Dangling Docker images are pruned with the same --older-than threshold: --dry-run enumerates and lists them without deleting, and --format json reports each as a docker-image detail. Tagged images (base images and the current :latest runner) are left untouched.

agents-sandbox image prune                      # use manual-prune-age from config (default: 7d)
agents-sandbox image prune --older-than 24h     # 24-hour threshold
agents-sandbox image prune --yes                # skip the confirmation prompt
agents-sandbox image prune --dry-run            # preview only
agents-sandbox image prune --format json        # machine-readable report on stdout

Flags:

Flag	Short	Default	Purpose
`--older-than`	—	`config`	Prune threshold. Falls back to `manual-prune-age` from config, then to `7d` (e.g. `24h`, `7d`).
`--age`	`-a`	—	Deprecated alias for `--older-than`. Hidden; still honored but warns. Setting both is an error.
`--dry-run`	`-n`	`false`	Show what would be pruned without deleting (no confirmation)
`--format`	—	`""`	Output format. `json` prints a structured report on stdout.

volume prune

Prune orphaned home volumes — volumes no project state file references and no adoption claim names — once the volume itself is older than --older-than, even when its slug has no VM. A volume still named by a project’s state or an adoption claim is never removed here — a project’s stated volume is deleted only by prune --purge (or volume remove). When a project’s last home volume is removed, its state file is removed too.

agents-sandbox volume prune                     # use manual-prune-age from config (default: 7d)
agents-sandbox volume prune --older-than 24h    # 24-hour threshold
agents-sandbox volume prune --yes               # skip the confirmation prompt
agents-sandbox volume prune --dry-run           # preview only
agents-sandbox volume prune --format json       # machine-readable report on stdout

Flags:

Flag	Short	Default	Purpose
`--older-than`	—	`config`	Prune threshold. Falls back to `manual-prune-age` from config, then to `7d` (e.g. `24h`, `7d`).
`--age`	`-a`	—	Deprecated alias for `--older-than`. Hidden; still honored but warns. Setting both is an error.
`--dry-run`	`-n`	`false`	Show what would be pruned without deleting (no confirmation)
`--format`	—	`""`	Output format. `json` prints a structured report on stdout.

sandbox prune

Prune stale sandboxes and leftover task workers. Task sandboxes fold into the VM count and have no age gate — a stopped task worker is transient and reclaimed regardless of age. Only project VMs are age-gated.

agents-sandbox sandbox prune                    # use manual-prune-age from config (default: 7d)
agents-sandbox sandbox prune --older-than 24h   # 24-hour threshold
agents-sandbox sandbox prune --yes              # skip the confirmation prompt
agents-sandbox sandbox prune --dry-run          # preview only
agents-sandbox sandbox prune --format json      # machine-readable report on stdout

Flags:

Flag	Short	Default	Purpose
`--older-than`	—	`config`	Prune threshold. Falls back to `manual-prune-age` from config, then to `7d` (e.g. `24h`, `7d`).
`--age`	`-a`	—	Deprecated alias for `--older-than`. Hidden; still honored but warns. Setting both is an error.
`--dry-run`	`-n`	`false`	Show what would be pruned without deleting (no confirmation)
`--format`	—	`""`	Output format. `json` prints a structured report on stdout.

df

Show storage usage of agents-sandbox’s private runtime home, grouped into the categories microsandbox reports (images, snapshots, branch memory, snapshot memory, sandboxes, volumes) plus the host-side runtime install (bin/lib). The table mirrors msb df; - means unknown. --verbose adds each category’s objects with their host paths, retention reasons, and accounting details. --format json prints a structured report shaped like microsandbox’s storage report (unknown counters are null). --format json and --quiet are mutually exclusive. Only the private runtime home is observed; a user’s own ~/.microsandbox is never touched. When the backend cannot report storage, the categories show as unknown and a note explains why.

agents-sandbox df                     # category totals
agents-sandbox df --verbose           # per-object rows and host paths
agents-sandbox df --format json       # machine-readable report on stdout
agents-sandbox df --quiet             # category names only

Flags:

Flag	Short	Default	Purpose
`--verbose`	—	`false`	List per-object rows and host paths
`--format`	—	`""`	Output format. `json` prints a structured report.

storage

Storage maintenance group. storage df and storage prune are aliases for the top-level df and prune commands.

agents-sandbox storage df --verbose
agents-sandbox storage prune --older-than 24h --yes

state repair

Quarantine a corrupt launcher-global state file (~/.local/state/agents-sandbox/state.yaml). An unparsable file blocks update checks, the runtime migration, and identity adoption; the error names this command. state repair renames the file to state.yaml.corrupt-<timestamp> and the next run starts from a fresh launcher state, so recorded update checks, migration progress, and adoption claims are lost. Nothing is deleted. A healthy or missing file is left alone, and a file written by a newer agents-sandbox is refused: upgrade instead. The command does not need the microsandbox runtime.

agents-sandbox state repair

list

List all sandboxes on this host (across all projects).

agents-sandbox list
agents-sandbox ls
agents-sandbox sandbox list
agents-sandbox list --quiet              # names only
agents-sandbox list --format json        # machine-readable output

Aliases: ls, sandbox list

Prints a header row followed by one line per agents-sandbox VM with columns NAME, IMAGE, STATUS, and CREATED. CREATED uses YYYY-MM-DD HH:MM:SS, matching microsandbox’s own sandbox listing. The STATUS cell is colored like microsandbox when color is enabled (running green, stopped/created dim, transitional states yellow, crashed red); with color disabled it renders as plain text.

The default output is the human table. Pass -q/--quiet to print identifiers only (one sandbox name per line), or --format json for structured output (a top-level array on stdout). The two are mutually exclusive.

Flags:

Flag	Short	Default	Purpose
`--label`	—	—	Filter to sandboxes carrying the given `KEY=VALUE` label. Repeatable; labels are AND-matched.
`--limit`	—	`0`	Limit the number of sandboxes listed (`0` = no limit).
`--running`	—	`false`	Only list running sandboxes.
`--stopped`	—	`false`	Only list stopped sandboxes.
`--names`	—	`false`	Deprecated alias for `--quiet`. Hidden; still honored but warns.
`--format`	—	`""`	Output format. `json` prints a top-level array of `{name,status,image,created,updated,labels}` objects.

--running wins over --stopped when both are set.

config

Inspect agent and home configuration.

agents-sandbox config
agents-sandbox cfg

Aliases: cfg

config agent [name]

Show the merged snippet config, the verbatim config-dir mirror files, and the host files drop-in-provisioned into the VM for an agent (default: the configured agent, opencode2).

agents-sandbox config agent opencode
agents-sandbox config agent --agent pi

Flags:

Flag	Short	Default	Purpose
`--agent`	—	`opencode2`	Coding-agent profile to inspect: `opencode`, `opencode2` (default), `pi`, `claude-code`, `codex`, `hermes`, or `oh-my-pi`.

The agent is resolved from the --agent flag, then the positional [name], then the configured agent, then opencode2. Passing both --agent and a positional [name] (conflicting values) returns an “ambiguous” error.

The output names the launcher (host) config dirs actually read, as absolute paths, one line per scope:

agent: opencode2
config dirs (primary):
  user: "/home/me/.config/agents-sandbox/opencode2"
  user: "/home/me/.config/agents-sandbox/myproject-<hash>/opencode2"
  project: "/work/repo/.agents-sandbox/opencode2"

One user: line is printed per user scope in precedence order — the generic user dir, then the per-slug user dir — and the project dir follows last. A dir that does not exist is marked (missing), e.g. user: "/home/me/.config/agents-sandbox/opencode2" (missing). The header label is primary when the agent’s own namespace is used, or legacy fallback "<namespace>" when the agent is reading a shared legacy namespace (see agent configuration). These are host launcher-config dirs; the guest agent config path is always ~/.config/opencode regardless.

Each host file is listed as merged (its VM path is the merged config path or part of the removed config-file family) or not merged (copied verbatim). Verbatim mirror files are listed as their host source path → VM path.

config paths

Print the launcher-config layers in precedence order (lowest to highest), the resolved path of each, and the repo slug.

agents-sandbox config paths

Each file layer is shown with its path, flagged (missing) when the file does not exist; the two environment layers show their variable-name globs, and flags is the CLI-flag layer:

config layers (lowest to highest precedence):
  generic user config  /home/me/.config/agents-sandbox
  per-project user config  /home/me/.config/agents-sandbox/myproject-<hash>  (missing)
  project config  /work/repo/.agents-sandbox  (missing)
  legacy env  OPENCODE_SANDBOX_*
  env  AGENTS_SANDBOX_*
  flags
repo slug:  myproject-<hash>

The layer lines are stdout; a guidance line naming the committed project config (.agents-sandbox/config.yaml) and the generic user config is stderr and survives --quiet. The command takes no flags (the global --quiet suppresses the layer block). The per-slug user config dir is keyed by the repo slug, so every clone of one remote shares it; that is the slug reported here (see Per-slug configuration).

config home

List the resolved home-file mappings from the config home: key (VM target path ← host source path).

agents-sandbox config home

completion

Generate the autocompletion script for the specified shell.

agents-sandbox completion bash         # bash completions (fish, powershell, zsh work the same)
agents-sandbox completion fish
agents-sandbox completion powershell
agents-sandbox completion zsh

image

Manage runner images.

agents-sandbox image
agents-sandbox img

Aliases: img

image list

List cached runner Docker images with reference, digest, size, and creation time. Only references whose parsed slug embeds the launcher’s 14-character hash are listed, so a manually loaded single-segment image in the private runtime home is omitted. The reference ends in the short content hash the image is keyed under in microsandbox; the digest column shows the short form (sha256: followed by 12 hex chars) as microsandbox reports it.

agents-sandbox image list
agents-sandbox image ls
agents-sandbox image list --quiet            # references only
agents-sandbox image list --format json      # machine-readable output

Aliases: image ls

The default output is the human table. Pass -q/--quiet to print references only (one per line), or --format json for structured output (a top-level array on stdout). The two are mutually exclusive.

image inspect

Show the full detail of a cached runner image: its reference, manifest digest, architecture, OS, size, creation time, the parsed OCI config (env, cmd, entrypoint, working dir, user, labels, stop signal), and every layer (diff ID, blob digest, media type, compressed and erofs sizes).

agents-sandbox image inspect myproj-1mjusbm3wikhb0:opencode-latest
agents-sandbox image inspect <ref> --format json   # structured output
agents-sandbox image inspect <ref> --quiet         # reference only

Args: ref — the image reference
Flags:
- --format json — structured output on stdout
- -q/--quiet — print the reference only

image remove

Remove one or more cached runner images by reference. Only runner images are accepted — the content-addressed microsandbox reference (<slug>:<agent>.<contentid>), the prefix-free name reference (<slug>:<agent>-latest), or a reference created by an earlier version (agents-sandbox/runner-<slug>:<agent>-latest); the parsed slug must embed the launcher’s 14-character hash, so any other reference — a registry image, or a manually loaded single-segment image without that hash — is refused, and --force does not override that ownership boundary. Refuses when a runner image is still in use — recorded by a project’s state file or held by a live project/task sandbox — naming the referencing projects, so an in-use image is never silently deleted; pass --force to remove it anyway. Prompts for confirmation unless the global --yes is set; non-interactively, --yes is required.

agents-sandbox image remove myproj-1mjusbm3wikhb0:opencode-latest
agents-sandbox image remove <ref>... --force   # remove even when still in use

Args: one or more ref
Flags:
- -f/--force — remove even when a project or sandbox still references the image
- --yes (global) — skip the confirmation prompt

Aliases: image rm

image build

Build or rebuild the runner image. Equivalent to the top-level build command.

agents-sandbox image build

sandbox

Parent command that groups sandbox-related subcommands. Most (run, shell, stop, kill, list) are also available at the top level; sandbox inspect, sandbox remove, and sandbox compact live only under this group.

agents-sandbox sandbox run
agents-sandbox sandbox list
agents-sandbox sandbox shell
agents-sandbox sandbox stop
agents-sandbox sandbox kill
agents-sandbox sandbox inspect myproj-aBc1234D-opencode

Aliases: sb

sandbox inspect

Show the full detail of a sandbox VM: its name, stable ID, status, image, backend kind, creation and update times, labels, mounts (guest path, kind, and source), and resources (memory and CPUs).

agents-sandbox sandbox inspect myproj-aBc1234D-opencode
agents-sandbox sandbox inspect <name> --format json   # structured output
agents-sandbox sandbox inspect <name> --quiet         # name only

Args: name — the sandbox name
Flags:
- --format json — structured output on stdout
- -q/--quiet — print the name only

sandbox remove

Remove a project sandbox VM by name. Only project VMs are accepted — the prefix-free <slug>-<agent> name or a name created by an earlier version (agents-sandbox-vm-*). A task sandbox name is refused, and --force does not override that. Refuses a running VM unless --force is set, which stops it first. The project’s persisted state is left intact, so the next run recreates the VM against the same recorded home volume. Prompts for confirmation unless the global --yes is set; non-interactively, --yes is required.

With --purge, remove the whole project instead of one VM — the same engine as prune --purge. The optional <name> is a project slug or a <slug>-<agent> key, defaulting to the current checkout; the project’s state, home volumes, runner images, and sandboxes are removed. A running sandbox fails fast unless --force stops it first.

agents-sandbox sandbox remove myproj-aBc1234D-opencode
agents-sandbox sandbox remove <name> --force                 # stop a running VM first
agents-sandbox sandbox remove --purge                        # purge the current checkout
agents-sandbox sandbox remove --purge myproj-1mjusbm3wikhb0  # purge a whole project

Args: name (optional with --purge) — the sandbox name, or the project target
Flags:
- -f/--force — remove a running VM (stopping it first); with --purge, stop and purge a running sandbox
- --purge — remove the project’s state, home volumes, runner images, and sandboxes
- --yes (global) — skip the confirmation prompt

Aliases: sandbox rm

sandbox compact

Merge the oldest sealed copy-on-write layers of each project VM’s disks into one, so long-lived VMs don’t build up ever longer layer chains. Without a name it compacts every project VM; task workers are skipped. Compaction covers the root disk and the VM’s own data disks. Named volumes, such as the home volume, are never compacted. A running VM is paused briefly while its layers are merged. Compaction never runs automatically; prune doesn’t trigger it. Only the local microsandbox backend supports it; other VMs are skipped.

The summary reports the layer count before and after, and the bytes materialized. That is the data the merge rewrote, not the disk space freed. --verbose adds one line per VM and per disk.

agents-sandbox sandbox compact --dry-run             # preview every project VM
agents-sandbox sandbox compact                       # compact every project VM
agents-sandbox sandbox compact <name> --root-only    # root disk of one VM only
agents-sandbox sandbox compact --layers 4            # merge only the oldest 4 layers

Args: name (optional) — the sandbox name; compacts only that VM
Flags:
- -n/--dry-run — report what would be compacted without changing disks
- --disk <path> — compact only the disk mounted at this guest path (/ is the root disk)
- --root-only — compact only the root disk; can’t be combined with --disk
- --layers <n> — merge only the oldest n sealed layers (at least 2; default: all)
- --format json — structured output on stdout

tree

Print the full command tree, showing every subcommand, alias, and flag.

agents-sandbox tree

doctor

Check the host prerequisites — Docker and the platform’s VM support (KVM on Linux, Apple Silicon on macOS) — and ensure the private microsandbox runtime is provisioned, then exit. Run automatically before run and shell; a failing check prints the command that fixes it and links to the matching troubleshooting section.

agents-sandbox doctor

version

Print version.

agents-sandbox version

upgrade

Check for and install the latest release, independent of the upgrade.mode/upgrade.interval settings that govern the automatic check on run/shell. Replaces the running executable with the release binary for your platform; the new version takes effect on the next invocation. For a Homebrew-managed install the command instead prints brew update && brew upgrade agents-sandbox, so Homebrew’s version bookkeeping stays accurate (see Self-upgrade).

agents-sandbox upgrade
agents-sandbox upgrade --channel canary     # one-shot override: upgrade from the canary line
agents-sandbox upgrade --channel stable     # leave the canary line for the newest stable release

--channel accepts stable or canary and applies to that invocation only, leaving the configured upgrade.channel unchanged. --channel stable on a canary install switches to the newest stable release even when that release is older; without the flag, upgrade never downgrades.

volume

The volume group provides manual home volume management.

Aliases: vol

`agents-sandbox volume list`

List all managed home volumes.

agents-sandbox volume list
agents-sandbox volume list --quiet           # names only
agents-sandbox volume list --format json     # machine-readable output

Columns: NAME, KIND, SIZE, CREATED (YYYY-MM-DD HH:MM:SS). SIZE shows capacity for disk volumes and quota for directory volumes, or - when unavailable.

The default output is the human table. Pass -q/--quiet to print names only (one per line), or --format json for structured output (a top-level array on stdout). The two are mutually exclusive.

Aliases: volume ls

`agents-sandbox volume inspect <name>`

Show the full detail of a home volume: its name, kind, host path, quota, used bytes, capacity, disk format, disk fstype, labels, and creation time.

agents-sandbox volume inspect myproj-aBc1234D-opencode-20260812T123456
agents-sandbox volume inspect <name> --format json   # structured output
agents-sandbox volume inspect <name> --quiet         # name only

Args: name — the volume name
Flags:
- --format json — structured output on stdout
- -q/--quiet — print the name only

`agents-sandbox volume migrate [volume-name]`

Create a new home volume and copy files from the old volume on top of it.

Args:
- [volume-name] — optional; defaults to volume in state file
Flags:
- --rm — remove old volume after successful migration
- --dry-run — show what would be done
- --agent — coding-agent profile to provision (opencode2 default)

`agents-sandbox volume reset [volume-name]`

Create a new home volume from the image contents only (fresh, no copy).

Args:
- [volume-name] — optional; defaults to volume in state file
Flags:
- --rm — remove old volume after reset
- --dry-run — show what would be done
- --agent — coding-agent profile to provision (opencode2 default)

`agents-sandbox volume edit [volume-name]`

Create a new volume alongside the old one, for manual data transfer.

Args:
- [volume-name] — optional; defaults to volume in state file
Flags:
- --rm — remove old volume after you exit (you are responsible for confirming)
- --dry-run — show what would be done

`agents-sandbox volume remove <name>...`

Remove one or more home volumes by name. Refuses when a volume is still referenced by a project’s state file (naming the referencing projects), so a project’s recorded home is never silently orphaned; pass --force to remove it anyway. Prompts for confirmation unless the global --yes is set; non-interactively, --yes is required. The next run of an affected project then starts a fresh home.

agents-sandbox volume remove myproj-aBc1234D-opencode-20260812T123456

Args: one or more volume-name
Flags:
- -f/--force — remove even when a project still references the volume
- --yes (global) — skip the confirmation prompt

Aliases: volume rm