Sandbox
required, fixture, and host: where tool closures run, and what lock eligibility requires.
Every agent has a sandbox mode. The default is required. The mode is set on the definition, not guessed at run time.
| Mode | Where tool closures run | Writes | Lock eligible |
|---|---|---|---|
required | Isolated, network-denied Node workers, from a staged source graph | Allowed inside the worker | Yes, when the rest of the build passes |
fixture | Host process. Trusted tests only | Blocked before execute | For fixture corpora |
host | This process, no worker | Execute | No |
Host mode is an explicit opt-in. It is never the default, and it is never isolation. A host-mode child under a required parent is refused, so a subagent cannot walk out of its root's containment.
compile refuses a host-mode agent with cave_host_sandbox_lock_ineligible before any search run. Live coding sessions therefore cannot produce a Cave Build. Coding agents that need a lock compile against fixture corpora with a contained sandbox.
Required mode#
Before provider traffic, the framework copies the project-relative source graph into a per-run immutable staging directory, imports tools only from that snapshot, and tears the staging down when the stream settles. RunOptions.entryPath must point at the module that exports the definition. The CLI fills this in. Programmatic run() of a tool-using required-sandbox agent without entryPath is refused.
The worker starts from a fixed environment baseline (LANG, LC_ALL, PATH, TZ, plus a fixture marker), not a spread of the parent env. One runtime-owned provider capability may be requested: ANTHROPIC_API_KEY, OPENAI_API_KEY, or the Google pair (GEMINI_API_KEY / GOOGLE_API_KEY as aliases). Signing, deployment, bootstrap, database, loader, and ambient secret names are denied.
Network egress is blocked at the OS: a network namespace on Linux (unshare --net), sandbox-exec (deny network*) on macOS. In-process monkeypatching is defence in depth, not the boundary. Requesting unbounded egress fails closed with cave_sandbox_network_egress_unbounded. There is no scoped-egress mechanism yet.
Linux unix-domain sockets are not covered by a network namespace. That gap is documented in the package threat model; do not treat required mode as a complete host firewall.
Windows#
Ordinary agent runs, runtime startup, and explicit sandbox: "host" coding tools work on native Windows through cmd.exe. sandbox: "required" is fail-closed on native Windows because the package has no verified OS network-isolation boundary there. Use WSL2 for production sandboxed tools. doctor reports cave_sandbox_os_network_isolation_unavailable and the WSL2 remedy. Do not replace required sandbox with fixture mode in production.
Fixture mode#
Trusted tests may set sandbox: "fixture". Closures run in the host process, which is why writes are blocked: a test that needs to observe a write belongs on a contained worker or an explicit host-mode agent, not in fixture.
What it will not do#
sandbox: "host" is not a synonym for isolation. Required mode is not available on native Windows. Fixture mode is not a production fallback. A passing doctor sandbox check is a containment probe, not a proof that every OS gap is closed.