What is boxer

boxer gives every agent workstream its own sandbox and runs the agent's commands in it. A workstream is a git worktree by default, or a single agent session or subagent. A sandbox is a microVM by default, or a container. Install boxer into your agent once, then work as usual.

Why

Codex and Claude Code create worktrees themselves, and orchestrators like Conductor run a task per worktree. Each worktree has its own files, but every task still shares your machine. Dev servers fight over ports, one task's install breaks another's, and every command runs against your own system. boxer gives each workstream its own sandbox:

• A sandbox per workstream: per worktree by default, including worktrees the agent or an orchestrator creates, or per session or subagent.
• Your agent doesn't change. A hook runs npm test in the sandbox instead of on your machine.
• No port clashes. Each worktree's dev servers get their own ports, or named URLs like https://fix-ui.myapp.localhost.
• A real boundary. A microVM with its own kernel by default, or a docker, podman or Apple container. It sees only the worktree.
• Fast. 33 ms per command, about the same as docker exec. See Benchmarks.
• Local. No account, no upload. See how it compares.

Do I need boxer?

Probably, if either of these is true:

• You run more than one agent at a time. Each one gets its own dev server, ports and installed tools, so they stop breaking each other.
• You let an agent run commands on its own. Its builds, tests and installs run in the sandbox instead of on your machine. Programs not on the intercept list, like rm, still run on your machine unless you add them.

boxer does not protect the code in your project. The sandbox works on your real files, so an agent that deletes them deletes them. See Security.

The terms, in one line each. A sandbox is a separate place for commands to run. A microVM is a small virtual computer with its own operating system, which is what boxer uses by default. A container is a lighter kind of sandbox that shares your machine's operating system core (its kernel). An image is the starting contents of a sandbox, such as Node on Linux. A worktree is an extra checkout of your git repository, so two tasks can edit the same project at once. Agents and orchestrators create worktrees for you. A hook is a script your agent runs before each command, which is how boxer steps in. An MCP server gives an agent extra tools. The Glossary has more.

Find your path

What happens while your agent works

Once boxer is installed into your agent, this happens on its own:

1. A session starts in a worktree. boxer's SessionStart hook creates that worktree's sandbox. It boots the image, runs your setup (such as npm ci) and starts your dev server. Then it tells the agent that commands run in a sandbox, which ones stay on the host, and where its dev server is.
2. The agent runs a command. It types npm test as usual. boxer's PreToolUse hook rewrites it to boxer run -c 'npm test' before the shell runs it. The command runs in the sandbox, and the agent gets the normal output and exit code.
3. A new worktree appears. It does not matter who creates it: codex --worktree, Claude Code's EnterWorktree, git worktree add from the agent's shell, or an orchestrator. boxer picks the sandbox from the directory each command runs in. The first command in the new worktree creates its sandbox, with the same setup and start. Two worktrees never share a sandbox.
4. A worktree is deleted. boxer removes its sandbox. Any command that uses a sandbox starts this cleanup in the background, at most every 6 hours (auto_reclaim). boxer gc runs it now.

git, gh and ssh always run on your machine, with your credentials. Everything in the intercept list (npm, node, python, go, make, cargo and more) runs in the sandbox.

What boxer install sets up

boxer install <harness> writes the files your agent reads. For Claude Code:

The hooks do the work. The other pieces tell the agent how the sandbox works.

How boxer connects to each agent

boxer uses the strongest integration each agent supports:

boxer install sets up the level for your agent. Kimi Code and DSH also need one line in boxer.toml to turn on tool mode. Inside mode is the strictest, but the agent's login and config have to reach the sandbox, so it is opt-in. Integration levels has the details, and where each level can be bypassed.

The default sandbox is a smolvm microVM. Apple container, docker and podman also work, with less isolation. See Backends. boxer runs on macOS on Apple Silicon, and Linux on x86-64 or arm64. On an Intel Mac, use docker or podman as the backend.