Parallel worktrees

Run several agents at once by giving each one a git worktree. boxer gives each worktree its own sandbox.

git worktree add ../myapp-feature -b feature
cd ../myapp-feature
boxer run -c 'npm test'      # its own sandbox, host port and node_modules

The default is isolation = "worktree". Two worktrees never share a sandbox, so two agents cannot overwrite each other's node_modules or race on a port.

Keep ports out of boxer.toml

Every worktree reads the same boxer.toml, so keep host-specific values out of it, ports most of all:

[network]
ports = ["auto:3000"]     # not "3000:3000"

A fixed host port fails with a busy-address error as soon as a second worktree starts.

Find each worktree's dev server

With auto:, every worktree gets its own host port, which is not the guest port. Run boxer status to see the port for the current worktree.

To give each worktree a name instead, turn on [urls]:

[network]
ports = ["auto:3000"]

[urls]
enabled = true            # needs portless: npm install -g portless

$ boxer up
boxer: url: https://fix-ui.myapp.localhost:1355 -> guest port 3000

Agents read the name with boxer url. For setup and naming rules, see Dev server URLs.

Size the sandboxes

Each sandbox has its own memory and disk. The default is cpus = 4 and memory = "4G" per sandbox.

In a measured run, each of four concurrent node sandboxes used about 1 GB of resident memory and 700 MB of disk. The host has to cover the allocation, so lower it if you run several:

cpus   = 2
memory = "2G"

See Manage sandboxes for the rest.

Orchestrators

Tools that cut a worktree per task (Conductor, T3 Code, Paperclip, herdr) get a sandbox per task. They need the integration committed on the branch they cut from, and boxer on their PATH. boxer install git is optional. It starts each sandbox as soon as the worktree is created, which matters for tools that time out on a cold start, such as T3 Code. See Orchestrators.