Troubleshooting

Run boxer doctor first. It resolves the same configuration a real command would, and reports configurations that load but do not keep commands in the sandbox.

boxer doctor

A command ran on the host

uname in the agent prints Darwin, or a file the command wrote appears outside the worktree.

Check these causes in order:

Cause	Fix
No integration is in effect. `boxer doctor` shows whether one is installed for this harness and enforcing.	Run `boxer install <harness>`.
The program is not on `intercept`. Only listed programs are sandboxed.	Add it to `intercept` in `boxer.toml`.
The harness uses a login shell. `zsh -lc` rebuilds `PATH` and puts system binaries ahead of shims. `boxer doctor` reports this.	Switch to hooks or tool mode. See integration levels.
Codex in a linked worktree. Codex reads project config from the main repository, so it never reads a `.codex/` in the worktree alone.	Run `boxer install codex` from the worktree, which writes both. Or run `boxer install codex --user`.
Project hooks are not trusted. Codex and Grok ignore project hooks until the folder is trusted.	Run `/hooks` once in Codex, or launch Grok once with `--trust`.
The integration is not on the branch. An orchestrator cut the worktree from a branch without the `boxer install` files.	Commit them on the branch the orchestrator starts from.
The orchestrator cannot find `boxer`. A GUI app may not see your shell's `PATH`.	Run `boxer doctor` in the task's worktree. See Orchestrators.

The sandbox will not start

Cause. A truncated environment pack, left by an interrupted pack create. boxer usually detects and rebuilds it.

Fix. Run boxer up --rebuild.

`exit 137` during setup

Cause. The guest's out-of-memory killer stopped the process.

Fix. Raise memory in boxer.toml (default 4G), or run fewer sandboxes at once.

docker, podman or Apple `container` refuses the default configuration

Cause. Those backends cannot enforce network.mode = "allowlist", which is the default.

Fix. Set network.mode to "on" or "off". See backends.

A download or install fails inside the sandbox

The guest shows an ordinary DNS or connect error, and boxer adds a line after it:

$ boxer run -c 'npm ci'
npm error network request to https://registry.npmjs.org/... failed
boxer: the egress allowlist refused registry.npmjs.org during this command
boxer: fix: add it to network.allow_hosts in boxer.toml, or set network.mode = "on"

Cause. The allowlist refused the host.

Fix. Follow the fix: line. boxer doctor lists every host the allowlist refused, under denied:.

Setup ran but dependencies are missing

A second worktree starts with no node_modules.

Cause. The install is in image_setup. image_setup is saved in the pack, and the worktree is not.

Fix. Move dependency installs to setup. See environment.

The dev server does not answer

`boxer up` passed but the server is not ready

Cause. The ready probe passed before the server could serve, or the server has crashed since. boxer restarts a crashed service, but a server that keeps crashing is given up on after five tries.

Fix. Make ready probe the real endpoint. The server's output is in /tmp/boxer-start.log in the guest, and boxer quotes its tail in the error.

The forwarded port does not answer, but `ready` passes

Cause. The server is bound to 127.0.0.1 in the guest.

Fix. Bind it to 0.0.0.0 in the guest. The host side stays on 127.0.0.1.

An agent started a second server

Cause. The agent could not reach the server you told it about. Inside the guest the server is at 127.0.0.1:<guest port>. The host-forwarded port does not exist there.

Fix. Give the agent the guest port. Or turn on [urls] and have the agent run boxer url.

A `[urls]` name refuses the connection

Cause. The portless proxy is down, for example after a reboot.

Fix. The next boxer up or boxer run in that worktree restarts it on port 1355. To start it by hand, run portless proxy start --port 1355.

A `[urls]` name answers 404

Cause. The name is not registered. Either the sandbox predates [urls], or its route was removed by hand.

Fix. Run boxer down && boxer up. boxer status prints the name.

`boxer: warning: urls.enabled is set but portless is not installed`

Cause. portless is not on PATH. Ports are still forwarded.

Fix. Run npm install -g portless.

Next.js refuses or warns about its dev chunks

Cause. The request's origin is not in allowedDevOrigins.

Fix. Add '127.0.0.1' and 'localhost' for a forwarded port, and '*.localhost' for a [urls] name. See URLs.

A command was refused for setting a `BOXER_` variable

Cause: the line sets one of boxer's own variables, such as BOXER_INSIDE=1 boxer run ... or export BOXER_MODE=off. Those are the operator's configuration, and a command setting them would change how boxer treats it, so the hook refuses the line.

Fix: run the command without the setting. To change how boxer behaves, set it in boxer.toml or in the harness's own environment before it starts.

A `start` service died

Cause: boxer restarts a crashed service after 1 second, then 2, 4 and up to 30. After five crashes in a row, each within 10 seconds of starting, it stops trying. With restart = "never" it does not restart it at all.

Fix: read /tmp/boxer-start.log in the sandbox. It has the service's output, a line for each restart, and gave up after 5 quick crashes when boxer stopped. Fix what it says, then run boxer restart to launch the services again without recreating the sandbox.

A dev server does not reload after an edit

Cause: your edits reach the sandbox's files, but on smolvm, Apple container and podman on a Mac they do not raise the events most watchers wait for. Next.js saw none of five edits on any of them. An edit made inside the sandbox, such as one the agent runs, is seen everywhere. OrbStack's docker passes your edits through.

Fix: boxer already sets polling for webpack and chokidar on those backends: WATCHPACK_POLLING=true and CHOKIDAR_USEPOLLING=1, unless [env] sets them. What is left is Turbopack, the default in Next.js 16, which has no polling that works there. Its watchOptions.pollIntervalMs did not help, and on Apple container it stopped even the sandbox's own edits from reloading. Run webpack instead:

start = ["npx next dev --webpack -H 0.0.0.0 -p 3000"]

boxer doctor warns a Next.js project about this. For a watcher outside Node, such as Spring DevTools or Rails, use its own polling option. To turn boxer's polling off, set the variable yourself, for example WATCHPACK_POLLING = "" in [env]. Polling costs some CPU on a large tree. See file watching for the measurements.

An interactive harness hangs

A harness in a terminal pane (herdr, for example) stops with no output.

Cause. It is waiting on a dialog that headless runs never show. This can be a permission prompt, a bypass-permissions confirmation, or a skill approval such as Use skill "boxer"?.

Fix. Read the pane. Grant every tool the agent needs in project settings, including Skill.

The harness fails to start in inside mode

`boxer shell claude` stops with a message about the macOS Keychain

Cause. The Linux guest has no Keychain, so a Keychain login does not reach it.

Fix. Run claude setup-token on the host and export CLAUDE_CODE_OAUTH_TOKEN. See inside mode.

The harness is missing or broken after an interrupted first run

Cause. The one-time install in the guest did not finish.

Fix. Run boxer up --recreate, then boxer shell <harness> again.

The first run is slow

The first boxer up in a repository takes minutes, and so does the second.

Cause. The first run pulls the image and runs image_setup. Later starts reuse the pack. If the second run is also slow, the pack key changed. The key includes image_setup, env, mounts, start and ready. See packs.

Fix. Keep those keys stable. Packs exist on smolvm only. On other backends image_setup runs once per sandbox.

The disk is full

boxer skips packing with a free-space message, or the host runs out of disk.

Cause. Stopped sandboxes and old packs.

Fix. Check what boxer uses, then remove stopped sandboxes and unreferenced packs. Running sandboxes are kept.

boxer ls --resources
boxer gc --all