CLI

boxer <command> [flags] [args]

A command with no sandbox name acts on the current scope, which is the git worktree you are in by default. boxer, boxer help, -h and --help print the usage text. boxer with no arguments prints it to stderr and exits 2.

stop, rm, backends, integrations add, install and package accept flags anywhere among their arguments. capsule inspect, capsule replay, fork rm and pack take the name first or last. Every other command wants its flags before any positional argument or --.

Commands

Identity flags

up, run, down, status, restart, doctor, brief, tasks, fork, fork ls, fork rm, pack save, pack use and pack rm accept these. They matter when isolation is session or subagent, and --harness selects the [harness.<name>] override layer.

boxer up

boxer up [--detach | --recreate | --rebuild]

Creates this scope's sandbox if it does not exist, starts it, runs setup and start, and waits for ready. It prints the name, the image and why it was chosen, and the mount.

boxer run

boxer run -c '<shell line>'
boxer run [flags] -- <program> [args...]
boxer run --task <name>

Runs one command in the sandbox and exits with its exit code. -c runs the line with sh -c. -- runs a program with no shell. Stdin, stdout and stderr pass through unchanged. The sandbox is created first when create_on includes run.

Without --tty, boxer allocates a terminal when both stdin and stdout are terminals. Inside a boxer guest, run executes the command directly, and exits 127 when the program cannot be started. From an agent, prefer --task. It runs a command the repository declared, regardless of what intercept catches.

boxer down

boxer down [--all | --scope NAME] [--json]

Deletes this scope's sandbox. A scope with no sandbox is not an error. A --scope name that matches no boxer sandbox is: it exits 1, so a typo is not taken for success. --all goes on past a sandbox it cannot delete, reports it with an error, and exits 1.

boxer status

boxer status [--scope NAME] [--json]

Prints this scope's sandbox: state, image, mount, forwarded ports and URLs. The exit code is the state.

boxer restart

boxer restart

Stops this scope's start services and everything they spawned, launches them again, and waits for ready. The sandbox and what is in it stay: an installed package, a database's files. It acts on this scope only and takes no --scope. Use it after changing something a server reads only at start, or when a service gave up after five quick crashes (see restart).

When a service cannot be signalled, as with docker under Ubuntu's AppArmor, boxer stops and starts the sandbox instead, which ends every process in it and keeps its files. Exits 1 with cause NO_SANDBOX when the sandbox is not running. Takes the identity flags.

boxer ls

boxer ls [-A] [--pr] [--resources] [--no-git] [--json]

Lists boxer's sandboxes on the configured backend with name, key, state, backend, branch, git state (clean, dirty(N) or gone), owner, the first URL or forwarded port, and worktree.

A backend that does not answer is named on stderr, and ls exits 1 after listing the backends that did.

boxer stop and boxer rm

boxer stop [NAME...] [--all | --gone | --stopped] [-A] [-i] [-y] [--json]
boxer rm   [NAME...] [--all | --gone | --stopped] [-A] [-i] [-y] [--volumes] [--json]

stop stops sandboxes without deleting them. rm deletes them and everything boxer kept about them: the run record, the last-used stamp, the lock and any URL. It keeps their named volumes unless you pass --volumes. NAME is a key (sb-7e1852e4a3c3) or a two-word name (swift-crab).

With no name and no filter, an agent or a pipe gets exit 2 and the command to run instead. A name that matches nothing exits 1. So does a backend that does not answer, even with --all, which would otherwise look like a host with nothing to act on. A sandbox that fails is reported and the rest are still acted on. When rm --volumes deletes a sandbox but not its volumes, the sandbox's row says removed: true with an error, and the command exits 1.

boxer gc

boxer gc [--all] [--dry-run] [--json]

Deletes sandboxes whose worktree is gone, fork children whose parent is gone, the named volumes of worktrees gone for 7 days, and packs past idle_timeout or beyond packs_keep_last. A running sandbox unused for its own repository's idle_timeout is stopped, or deleted with idle_action = "delete". It skips a sandbox a command is provisioning, a parent whose fork child is in use, and a pack a create is using. It never deletes a named pack. It looks only at the configured backend; a sandbox left on another one after backend changed is named the next time this worktree's sandbox is created.

boxer url and boxer open

boxer url [PORT]
boxer open [PORT]
boxer url --all
boxer open --all

Prints the address of this worktree's server, which is its [urls] name or else http://127.0.0.1:<host port>. PORT is the guest port. The default is the first forwarded port, sorted as text. open also opens the address in a browser when a person is at the terminal. The command exits 4 when this scope has no sandbox. It exits 1 when the sandbox forwards no ports, or not the one you named.

--all lists every running sandbox's servers on the configured backend, one name<TAB>address line each, and works outside a repository. open --all also opens each one. It exits 1 when no running sandbox forwards a port.

boxer backends

boxer backends [NAME] [--probe] [--json]

Lists smolvm, docker, podman and container: installed or not, version, answering or not, boundary, allowlist support, sandbox count, and known misconfigurations. NAME shows one. Exit 1 when the configured backend is missing or not answering, or a probe failed. Exit 2 for an unknown name.

boxer integrations

boxer integrations [--json]
boxer integrations add <name> [--user] [--agent NAME] [--source REPO]

Alias boxer harnesses. It lists:

• every harness, with whether its program is on PATH and whether boxer's files are installed in this repository and for this user
• the orchestrators conductor and git-hook
• the tools portless, gh and npx

Files written by another boxer release are marked stale.

add installs one integration. A harness name, all, git or conductor runs boxer install. skill runs npx skills add <source> --skill boxer, and plugin runs npx plugins add <source>. See skills and plugins.

boxer doctor

boxer doctor [--json]

Prints the version, the backend's capabilities, the git checkout, every configuration file read, each resolved setting with the file or variable it came from, the scope, the image, the sandbox, the environment pack, shims, hook signals, disk use, refused hosts, and warnings about configurations that look correct but do not work. Exit 1 when the configuration could not be resolved.

boxer brief

boxer brief [--json]

Prints the brief the hooks inject and the MCP resource serves: the mount, the mode, the intercept and passthrough lists, and each declared task.

boxer tasks

boxer tasks [--json]

Prints each [tasks] entry's name and description, or its command when it has none.

boxer fork

boxer fork --prepare [--count N] [--json]
boxer fork [--count N] [--json]
boxer fork ls [--json]
boxer fork rm <name> | --all

Branches copy-on-write children off this scope's smolvm sandbox. Children share this worktree. See forking. Stdout carries only the children's names.

fork ls lists this scope's children. fork rm <name> removes one child and fork rm --all removes all of them. A name that is not a fork child exits 2.

boxer trust

boxer trust
boxer trust --show

Approves this worktree's host-affecting configuration. The worktree is mounted read-write, so code in the sandbox can rewrite boxer.toml or devcontainer.json, which boxer reads on the host. The keys that reach the host — prep, mounts, build, mode, enforcement, passthrough, intercept, secrets, env_passthrough, network, on_sandbox_unavailable, telemetry.path and [harness.*] overrides — are held back until a person who has seen the configuration runs this. Until then the sandbox still runs, with boxer's defaults for those keys; everything else (image, cpus, tasks, ready) takes effect without approval.

--show lists the host-affecting keys and exits without approving. Trust is per worktree, and a changed set of those keys has to be approved again. BOXER_TRUST=1 approves every configuration without a prompt, for CI and other places the repository is yours to begin with.

boxer pack

boxer pack save <name>
boxer pack ls [--json]
boxer pack use <name>
boxer pack rm <name>

A named pack is a snapshot of a sandbox's filesystem, not its processes. See packs you name.

boxer checks a pack name before use because it becomes a path segment. An invalid name exits 2.

boxer capsule

boxer capsule new [-o PATH]
boxer capsule inspect <path> [--json]
boxer capsule replay <path> [--allow-dirty] [--allow-drift] [--apply-patch]

A capsule records the last command run in this scope well enough to run it again. See capsules.

replay exits 0 when the failure reproduced, which means the same exit code and, when the capsule lists failing tests, the same failing tests. It exits 1 when it did not reproduce or was refused.

boxer logs

boxer logs [--scope NAME] [-n N] [--json]

Prints the event log when the file sink is on. Exit 1 when there is no log.

boxer watch

boxer watch [-A] [--interval 1s] [--json]

Streams sandbox state changes on the configured backend, and events from the file sink when it is on, until interrupted. Exit 1 when the backend cannot be listed.

boxer install

boxer install <harness>... [--user]
boxer install all [--user]
boxer install git
boxer install conductor

Writes the files a harness reads so its commands reach the sandbox: hooks or a plugin, and, where the harness takes them, an MCP entry, an instruction file and the skill. Each harness's setup page lists exactly what it writes. Run it inside the repository.

boxer uninstall

boxer uninstall <harness>... [--user]
boxer uninstall all [--user]
boxer uninstall git
boxer uninstall conductor

Removes what the same boxer install wrote, and only that. Files boxer created go. In files it merged into (.claude/settings.json, .mcp.json, AGENTS.md, opencode.json), only boxer's entries go and the rest of the file is kept, including your own hooks in a group boxer's hook shares. Directories left empty are removed. Running it twice is harmless.

Some files serve several harnesses: .mcp.json's boxer server (Claude Code, Grok), the skill in .agents/skills/boxer (Codex, Grok, Kimi, DSH) and the AGENTS.md section (OpenCode, pi). Each is kept while another harness that uses it is still installed, and removed with the last of them.

Left for you, and named in the output: the tools.exclude entry in Gemini CLI's settings, which may be yours too; the hooks you appended to ~/.kimi-code/config.toml by hand; and an opencode.json left holding only $schema, which boxer cannot tell from one you wrote.

boxer shim install

boxer shim install [dir]
boxer shim install --harness a,b [dir]
boxer shim install --shell [dir]

Writes files on PATH that forward to boxer. See PATH shims.

boxer removes its own shim directories from PATH when it starts, so it never calls itself through a shim.

boxer shell and boxer acp

boxer shell <harness> [-e KEY=VALUE]... [-- args...]
boxer acp <harness> [-e KEY=VALUE]...

shell runs the harness itself in the sandbox, with a terminal when you have one. acp runs its ACP server in the sandbox with stdio piped. Both set integration = "inside". See running the harness inside.

Harnesses are claude, codex, copilot, fx, gemini, grok, kimi, opencode and pi. fx and pi have no ACP server.

boxer hook

boxer hook <harness>

The command a harness hook runs. It reads the hook's JSON on stdin and answers on stdout. Harnesses are the install names above plus copilot. An unknown harness exits 1. Input that is not JSON exits 0, so a parse failure in boxer never breaks a session. Inside a guest it does nothing.

boxer mcp

boxer mcp [--harness NAME]

Serves MCP over stdio. See MCP server.

boxer package

boxer package plugin|skills|<harness>|all [--out DIR]

Renders what boxer publishes. You need it only to release boxer.

The output is the same for every user apart from the version. Configuration reaches the agent at run time through boxer brief, the hooks and the MCP resource.

boxer completion

boxer completion bash|zsh|fish

Prints a completion script for the command names.

boxer version

boxer version

Also --version and -v. Prints the release version, else the module version go install recorded, else dev.

Exit codes

A refusal prints boxer: <reason> on stderr with scope, worktree, cause and fix lines. The causes are listed under errors. With on_sandbox_unavailable = "passthrough", run runs the command on the host when the sandbox cannot be provisioned, and exits 127 when the program cannot be started there.

Output modes

ls, stop, rm, backends and integrations format their output in one of three modes. open starts a browser only in human mode.

boxer detects an agent when CLAUDECODE, BOXER_AGENT or BOXER_INSIDE is set. A command that would have asked a person refuses in agent mode and says what to pass. BOXER_OUTPUT=json also switches every other command that has a JSON form.

Environment variables

Variables that set a boxer.toml key, such as BOXER_BACKEND, are listed in the configuration reference. These have no key.

boxer sets these for the processes it starts.