Overview

An orchestrator creates a git worktree for each task and starts an agent in it. boxer keys a sandbox to each worktree, so every task gets its own, and boxer gc removes it once the worktree is gone.

What every orchestrator needs

1. Commit the integration. The orchestrator cuts each worktree from a branch. If the files boxer install writes are not on that branch, the task runs on your machine.

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

2. Optional: warm the sandbox when the worktree is created.

boxer install git

This adds a post-checkout hook that runs boxer up --detach in every new worktree, so the sandbox is booting before the agent starts. Without it, the first command waits for a cold boot. T3 Code times out on that and needs it. For the others it only saves time. boxer install all does not do this, so run it separately.

3. Put boxer on the orchestrator's PATH. Hooks and shims call boxer, and boxer calls your backend's program (smolvm, docker), so both must be where the orchestrator looks. See below.

Put boxer on the orchestrator's PATH

A terminal orchestrator inherits your shell's PATH. A GUI app such as Conductor may not read your shell profile. To check, run boxer doctor from a task's terminal. If boxer is not found, install it where every process looks:

curl -fsSL https://raw.githubusercontent.com/BarakChamo/boxer/main/install.sh | sudo BOXER_INSTALL_DIR=/usr/local/bin sh

Run many tasks at once

Each sandbox is allowed 4 CPUs and 4 GB of memory by default. A sandbox serving a Next.js dev server uses about 1.2 GB inside the guest (Benchmarks). To run more tasks at once, lower the limits in boxer.toml:

cpus = 2
memory = "2G"

A new sandbox takes longest the first time: the image downloads and setup runs. On smolvm, a repository with image_setup caches the result, so the next worktree skips it. boxer ls --resources shows what each sandbox uses.

Clean up

Orchestrators delete worktrees without telling boxer. boxer's background sweep (auto_reclaim, every 6 hours by default) removes their sandboxes. To do it now, boxer rm --gone -A -y removes only sandboxes whose worktree is gone, on every backend. boxer gc also stops idle sandboxes (or deletes them, with idle_action = "delete") and removes unused caches.

boxer rm --gone -A -y

Why not a user-level plugin?

Several orchestrators give each agent its own config directory (CLAUDE_CONFIG_DIR, CODEX_HOME), which does not include your ~/.claude/plugins. The committed project layer is in the worktree itself, so it applies whatever config directory the agent gets.