boxer

Parallel coding agents, each in its own sandbox. An isolated sandbox for every agent workstream, with its own dev server and URL. A microVM or a container, set up once per agent.

Documentation · Quickstart · Compared with

Highlights

• A sandbox per workstream. One per git worktree by default, including worktrees the agent or an orchestrator creates, or one per agent session or subagent. Cleaned up when the work is done.
• Your agent doesn't change. npm test, pytest and make run in the sandbox. Output and exit codes come back as usual.
• No port clashes. Each worktree's dev servers get their own ports, or named URLs like https://fix-ui.myapp.localhost with portless.
• MicroVM or container. A smolvm microVM with its own kernel and a network allowlist by default, or a docker, podman or Apple container.
• Fast. 33 ms per command, about the same as docker exec.
• Works with your setup. Your own images and devcontainer, and services like Postgres running in the sandbox.
• Works with your tools. Claude Code, Codex, Gemini CLI, Copilot CLI, OpenCode, pi, Grok, Kimi Code, Conductor, T3 Code and more.

Install

curl -sSL https://smolmachines.com/install.sh | bash                                  # smolvm
curl -fsSL https://raw.githubusercontent.com/BarakChamo/boxer/main/install.sh | sh    # boxer

Or go install github.com/BarakChamo/boxer/cmd/boxer@latest. macOS on Apple Silicon (Intel Macs with docker or podman), Linux on x86-64 or arm64.

Get started

cd your-repo
boxer install claude-code
git add .claude .mcp.json && git commit -m "Run agent commands in boxer"

Then:

1. A session starts in a worktree. boxer creates that worktree's sandbox, runs your setup, starts your dev server, and tells the agent where it is.
2. The agent runs npm test. The hook runs it in the sandbox. The agent sees the normal output.
3. Another session starts in another worktree. It gets its own sandbox, with its own ports, tools and processes.
4. A worktree is deleted. Its sandbox is removed.

$ boxer ls        # two agent sessions, two worktrees (some columns left out)
NAME         STATE    BRANCH    SERVES
mild-lynx    running  add-auth  https://add-auth.myapp.localhost:1355
olive-comet  running  fix-ui    https://fix-ui.myapp.localhost:1355

git, gh and ssh stay on your machine. See the Quickstart.

Works with

Agent	Setup
Claude Code	boxer install claude-code
Codex	boxer install codex, then trust the hooks and turn off Codex's own sandbox (why)
Gemini CLI	boxer install gemini-cli
Copilot CLI	boxer install copilot --user
OpenCode	boxer install opencode
pi	boxer install pi
Grok	boxer install grok
Kimi Code, DSH	boxer install kimi, boxer install dsh, plus tool mode
fx, or any other agent	boxer shell <harness> runs the agent itself in the sandbox

Orchestrators: Conductor, T3 Code, Paperclip, herdr, Multica and OpenHands.

boxer uninstall <harness> removes what boxer install wrote, and leaves the rest of each file as it was.

Find your path

You are	Start here
Using Claude Code or Codex	Quickstart
Running Conductor, T3 Code or another orchestrator	Orchestrators
Managing containers with your own scripts and hooks	Coming from your own scripts
Using Docker, your own images, or services like Postgres	Bring your Docker setup
New to containers and VMs	What is boxer, then the Quickstart

Configure your project

A boxer.toml at the repository root describes the sandbox. Without one, boxer picks an image from your lockfile.

image = "mirror.gcr.io/library/node:24-alpine"
setup = ["npm ci"]                        # once per worktree
start = ["npx next dev --webpack -H 0.0.0.0 -p 3000"]   # 0.0.0.0; webpack reloads on host edits
ready = "wget -q -O /dev/null http://127.0.0.1:3000/"

[network]
allow_hosts = ["registry.npmjs.org"]      # everything else is blocked
ports = ["auto:3000"]                     # a free host port per worktree

[urls]
enabled = true                            # https://<branch>.<repo>.localhost:1355, needs portless

Examples cover Next.js, Vite, Python, Go and monorepos. Configuration lists every key.

Backends

Backend	Isolation	Egress allowlist
smolvm (default)	own kernel per sandbox	yes
Apple container	own kernel per sandbox	no
docker, podman	one shared kernel	no

Set backend = "docker" and network.mode = "on" in boxer.toml to switch. You do not need smolvm then. See Backends and Bring your Docker setup.

Documentation

• What is boxer and the Quickstart
• Set up your agent and your orchestrator
• Set up your project: images, dependencies, dev servers, URLs
• Security: what is isolated and what is not
• CLI, Go package and JSON
• Evaluations and benchmarks

Development

make build    # bin/boxer
make test     # unit tests, race detector, coverage floors
make smoke    # every configuration path against a real sandbox
make docs-dev # the docs site on localhost

See CONTRIBUTING.md and docs/architecture.md.

License

Apache-2.0. Report vulnerabilities as described in SECURITY.md.