Sandbox backends
Backend overview
Section titled “Backend overview”| Backend | Value | Platform | Availability |
|---|---|---|---|
| Enclosed VM | microvm |
macOS, Linux, Windows (microVM hypervisor) | Probe-gated on the microVM runtime; applies to interactive terminals — the shell runs inside a rig, not on the host |
| Native | native |
macOS (Seatbelt), Linux and WSL2 (bubblewrap) | Probed at boot; Linux refuses a run requiring filename-glob write denies, which bubblewrap cannot enforce |
| None | none |
All | The parse default and the terminal’s default; agent dispatch uses it under --sandbox off, and for the owner’s own runs when no backend is available |
SandboxBackend.fromName returns none for a null or unrecognised stored value.
microvm is the one backend with a kernel boundary — the workload
genuinely does not run on the host. It is never a silent fallback in either
direction: explicitly requesting it on a host that cannot boot a VM fails
loudly (“I asked for a VM and got my laptop” is the one degradation the
enclosure cannot afford), and only an unspecified default steps down to
native, with a log line saying so. The session’s actual backend is reported
back to the client and badged, so a terminal can never claim to be enclosed
while running on the host. Lifecycle, images and egress for the VM itself are
covered by the rigs reference.
Windows has no native sandbox. NativeSandboxAdapter.probe returns available: false on every host that is not macOS or Linux/WSL2, so a Windows server is unavailable: only the server owner’s agent runs start, unconfined, and everyone else’s are refused. To let every member run agents there, the owner starts the server with --sandbox off, which runs all of them unconfined. The microvm backend is separate: it is probe-gated on the microVM runtime and applies to interactive terminals and rigs, not to wrapping bash on the host.
Probe results
Section titled “Probe results”The probe is what gates enforcement. It runs once, at server boot.
| Host | available |
Note / hint |
|---|---|---|
| macOS | true |
sandbox-exec (Seatbelt) — namespace isolation, no kernel boundary |
Linux or WSL2 with bwrap and socat |
true |
bubblewrap — namespace isolation, no kernel boundary |
| Linux or WSL2 missing either tool | false |
requiresInstall: true, with an install hint naming the missing packages |
| Any other platform | false |
Native sandbox is not offered on this platform |
The server logs the outcome on one startup line: agent sandbox ON plus the note; no OS-native agent sandbox on this host plus the hint, which adds that only runs the server owner is accountable for will start; or agent sandbox DISABLED by --sandbox off. The exposure line printed at startup carries the same decision as sandbox=native, sandbox=off or sandbox=unavailable. GET /healthz carries no sandbox field.
--sandbox / CC_SERVER_SANDBOX accepts on (default) or off. on wraps every run when the host offers a backend and admits only the owner’s runs when it does not. off runs every member’s agents unconfined on this host; it is the owner’s choice for everyone, not a per-run setting.
Native backend
Section titled “Native backend”macOS: Seatbelt
Section titled “macOS: Seatbelt”Uses Apple’s Seatbelt sandbox mechanism (the same system used by macOS App Sandbox).
The generated profile is permissive by default ((allow default)) and carves out denies, because a fully deny-by-default profile makes an interactive shell unusable — there are too many dyld, XPC and Mach calls to enumerate. The practical consequence is that an agent can still read most of the host; your registered checkouts are protected by explicit write and rename denials, not by invisibility.
- Filesystem reads: denied for the secret paths (
~/.ssh,~/.aws,~/.gnupg,~/.config/gh,~/Library/Keychainsand the rest of the deny-read set) - Filesystem writes: reset to deny, then explicit subpath allows, with the mandatory-deny paths (shell rc files,
.git/hooks, Claude config, protected checkouts) blocked even inside a writable root.file-write-unlinkis denied on every denied path and its ancestors, so a rename cannot bypass a write-deny - Process:
process-execdenies for the always-dangerous binaries, plus a block on executing anything from a writable directory. Known toolchain install trees under your home (corepack, npx andpnpm dlxcaches, node version managers, Playwright browsers, rustup and cargo, Go, fvm and the pub cache, pyenv, uv and pipx, rbenv, sdkman, mise, asdf and~/.local/bin) are re-opened beneath that block. The shared temp directories are blocked too. Each session instead gets a privateTMPDIRunder/private/tmp, where programs it builds (ago testbinary, a cargo build) can run. The always-dangerous denies are applied after these allows - Network: restricted to the in-process proxy ports plus DNS — loopback is not blanket-allowed and TCP listening is denied. Unix sockets are allowed only inside the session’s private
TMPDIR, which covers tools such as tsx and Chrome that keep an IPC socket there; your SSH agent and other sockets stay unreachable. The proxies enforce the per-session domain allowlist (see Network egress) - Configuration: profiles are generated per launch from the
SandboxSpec - The server’s own commands: no direct child of a folder the server runs programs from (every
PATHentry and the usual per-user tool folders such as~/.local/bin, with version-manager links like~/fvm/defaultresolved) can be created, replaced, deleted or renamed, nor the installed package a linked command points into. See The server’s command folders - Start-up files: every home path the profile denies reading is also denied writing, and the start-up files of the server user’s shells and sessions (
.zshenv,.zlogin,.bash_login, fish config, systemd user units, autostart entries and the like) are write-denied in every mode
Requirements:
sandbox-exec(/usr/bin/sandbox-exec), part of every macOS install — no additional tooling required
Linux: bubblewrap
Section titled “Linux: bubblewrap”Uses bubblewrap (bwrap) to create mount and PID namespaces.
- Filesystem: creates a mount namespace with only the bound paths visible
- Network: runs in an unshared network namespace; traffic reaches the host proxies through
socatUnix-socket bridges - Process: PID namespace isolation
- The server’s own commands and start-up files: the same protections as on macOS, expressed as bubblewrap binds. They are not verified on Linux yet, and a missing command folder there can still be created
Requirements:
bubblewrapandsocatinstalled (sudo apt-get install bubblewrap socaton Debian/Ubuntu)- Kernel namespace support (standard on modern Linux)
Bubblewrap can shadow an existing path but cannot forbid a new .env,
*.key or *.pem file inside a writable bind. The standard dispatch policy
requires these filename-glob denies, so native agent dispatch currently
fails closed on Linux/WSL2 even when the probe finds bubblewrap. It does not
run with a silently weaker policy. A backend with create-time filename rules
is required to restore Linux native dispatch. Disabling sandboxing is an
explicit unconfined opt-out, not an equivalent workaround.
In practice a Linux or WSL2 server runs agents today in one of two ways.
Started with --sandbox off, it runs every member’s agents unconfined. Without
bubblewrap or socat installed, it is unavailable and runs the server owner’s
agents alone, unconfined. With both tools installed and the sandbox on, every
run fails closed, the owner’s included.
The server’s command folders
Section titled “The server’s command folders”The server finds, once at start, every folder it runs programs from: each entry of its PATH, the per-user tool folders it probes (such as ~/.local/bin, ~/.bun/bin and the npm, yarn and pnpm global folders), and the real folder behind every link on the way (version-manager links such as ~/fvm/default or an fnm default). Inside a sandbox, an agent cannot add, replace, delete or rename a command in those folders, the link leading to one, or the installed package a linked command points into, and cannot rename the folders above them. Otherwise a sandboxed run could plant a program that the server, or the person, later starts outside the sandbox.
What this changes for a run:
- Global installs from inside a sandboxed run fail with “Operation not permitted”:
npm i -g,pnpm add -g,yarn global add,bun add -g,corepack enable,pipx install,uv tool install, andcargo install,go installordart pub global activatewhen their bin folder is on the server’sPATH. - Switching a default version fails the same way (
fnm default,nvm alias default,fvm global), as does a tool updating itself in place. - Project-local installs (
node_modules/.bin),npx,pnpm dlx, package managers managed by corepack, SDK caches and normal builds keep working.
To make a global tool available to agents, install it on the server itself, as the server’s user, and restart the server so the new command is protected too. Or install it in the project. A command installed after the server started is fully protected only from the next start.
Enforced and tested on macOS. On Linux the same rules are bubblewrap binds that are not verified yet. Windows has no sandbox.
None backend
Section titled “None backend”No sandboxing. The process runs directly on the host with the host’s filesystem, network and process access. ACP and the harness bash tool still get environment sanitisation and the command policy; Claude Code through NoSandboxAdapter inherits the host environment. Agent dispatch uses it for every run under --sandbox off, and on a host with no available backend for the server owner’s own runs only; anyone else’s run is refused there. For a terminal it is the host shell, which only the server owner may open.
Server-hosted terminal
Section titled “Server-hosted terminal”The server-hosted terminal opens the host shell only for the server’s owner. Everyone else gets a sandboxed terminal, with an agent’s limits, in the workspace’s own directories.
How the backend is chosen for a session:
| Asked for | Server owner | Anyone else |
|---|---|---|
| Nothing | The server’s default backend | The default, with none replaced by native |
none (the host shell) |
Host shell | Refused: the host shell runs on the server without a sandbox |
native |
Native sandbox, owner profile | Native sandbox, agent profile |
microvm |
Enclosed VM | Enclosed VM |
| An unknown name | Refused | Refused |
- Owner profile.
$HOMEand the session’s working directory are writable, the network is open, and~/.ssh,~/.aws,~/.gnupg,~/.config/ghand~/Library/Keychainsare read-denied. - Agent profile (
memberTerminalSandboxConfig). The same policy an agent in that workspace runs under: writes stay in the working directory, a private run directory,/tmpand the parts of$HOMEan agent may write; secrets are read-denied; the network is the agent egress allowlist; programs run only from the working directory and installed toolchains. - A terminal opens only inside the workspace’s own directories. A working directory outside them is refused, never swapped for another.
- Only the person who opened a terminal can read, type into, resize or close it. To anyone else its id looks unknown.
microvmasked for explicitly on a host with no rig service fails instead of falling back. Amicrovmdefault on such a host steps down tonativeand says so in the log.
The read-only forge token and the push gateway do not apply to terminals: they are dispatch concerns. If the wrap is unsupported, the session fails instead of showing a sandbox badge on a host-shell session.
Network egress
Section titled “Network egress”When a sandbox is launched, outbound network access is enforced by in-process proxies, not by kernel firewall rules. A run that is not sandboxed (every run under --sandbox off, or the owner’s run on a host with no backend) gets none of this: a process it spawns reaches the network exactly as the server user would.
- The sandbox runtime runs an HTTP/HTTPS proxy and a SOCKS5 proxy on
127.0.0.1inside thecc_serverprocess, one pair per restricted session (http_proxy.dart,socks_proxy.dart). Concurrent runs do not share a pair. - Sandboxed processes receive proxy environment variables (
HTTP_PROXY/HTTPS_PROXY→ the HTTP proxy,ALL_PROXY→ the SOCKS proxy;GIT_SSH_COMMANDroutes git-over-SSH through the SOCKS proxy). On Linux the network namespace is unshared, so the proxies are the only way out; on macOS the sandbox shares the host loopback and talks to them directly. - Each connection’s target host is matched against the session’s domain allowlist; anything else is denied. Two wildcard forms, each with exactly one
*: a leading*.example.commatches any subdomain (includinga.b.example.com) but not the apex itself; a middle-labelbedrock.*.amazonaws.commatches exactly one label (bedrock.us-east-1.amazonaws.com, notbedrock.evil.attacker.amazonaws.com). - The allowlist is resolved per session from the curated baseline (
kBaselineAllowedDomains: LLM providers, Git hosting, package registries), plus the GitHub domains (kGithubDomains), plusSandboxSpec.egressAllowlist. The dispatch path never passes extraegressAllowlistentries, so in practice every run gets the baseline plus GitHub. - A fixed deny list (
kBaselineDeniedDomains: cloud metadata endpoints, telemetry sinks) takes precedence over all allows. networkEnabled: falsestill starts the per-session proxies, but the allowlist is empty so every outbound connection is refused. Dispatch sets it from the Access the network rule when the run starts: a deny turns the network off, allow and ask first leave it on.
SandboxSpec
Section titled “SandboxSpec”The specification passed to SandboxPort.launch:
| Field | Type | Description |
|---|---|---|
sessionId |
String |
Stable session identifier (typically the space id) |
workspaceId |
String |
Owning workspace id |
agentId |
String? |
Agent currently bound to the sandbox, if any |
bindMounts |
List<SandboxBindMount> |
Host→guest mounts; the sandbox sees only the host paths listed here |
networkEnabled |
bool (default true) |
Set at dispatch from the network-egress rule (off only when it resolves to deny). When off, per-session proxies still start but the allowlist is empty so every outbound connection is refused |
egressAllowlist |
List<String> (default []) |
Extra allowed egress domains; wildcards supported (*.example.com, plus a one-label middle form). Dispatch never populates this, so a wrapped run gets the curated baseline plus GitHub domains |
guestWorkdir |
String? |
Default working directory inside the sandbox; individual exec calls can override it |
mode |
Mode (default chat) |
Carves the filesystem write rules: chat keeps bind mounts writable; review, plan and orchestrate are read-only |
protectedPaths |
List<String> (default []) |
Host paths that must never be writable inside the sandbox, in any mode |
runnerStateDirs |
List<String> (default []) |
Host directories the runner keeps its own state in, writable in every mode (a Control-Center-managed CLAUDE_CONFIG_DIR is the current one) |
execGrantRoots |
List<String> (default []) |
Operator-approved directory trees that re-open the writable-dir exec block on macOS. Linux ignores them — bwrap has no $HOME exec block to re-open |
protectedPaths holds the original registered repo checkouts, resolved per dispatch from the workspace’s repos. Agents work exclusively in per-conversation copy-on-write worktrees, so the originals must never be writable from inside the sandbox — on macOS, Seatbelt’s blanket $HOME write allowance would otherwise leave them writable via bash. They join the secrets deny-write set in every mode, chat included.
Every deny-read and deny-write path is emitted in both its literal spelling and its symlink-resolved one. The kernel matches a deny rule against the resolved path, so a rule written against a symlinked path never fires — and on macOS that is the common case rather than the exotic one, since /tmp resolves to /private/tmp and /var/folders/… to /private/var/folders/…. Entries containing * or ? are treated as globs and left alone; a path that does not resolve is kept as written.
SandboxBindMount
Section titled “SandboxBindMount”| Field | Type | Description |
|---|---|---|
hostPath |
String |
Absolute path on the host |
guestPath |
String |
Path inside the sandbox (with the native sandbox this equals hostPath; retained for adapter symmetry) |
readOnly |
bool (default false) |
Mount read-only when true |
SandboxHandle
Section titled “SandboxHandle”Returned by SandboxPort.launch:
| Field | Type | Description |
|---|---|---|
sessionId |
String |
Session identifier |
backend |
SandboxBackend |
Which backend is running |
state |
SandboxState |
Lifecycle state |
error |
Object? |
Set when state is error |
details |
Map<String, Object?> |
Adapter-private bookkeeping (working directory, PID, profile path, etc.) |
SandboxState
Section titled “SandboxState”| State | Description |
|---|---|
created |
Spec created but the VM has not started yet |
warm |
Running and ready to exec commands |
active |
Currently executing a command |
suspended |
Paused / checkpointed to disk to save RAM |
destroyed |
Torn down; the handle is no longer valid |
error |
Launch failed — see SandboxHandle.error |
Sandbox events
Section titled “Sandbox events”| Event type | Description |
|---|---|
stdout |
Standard output from the sandbox |
stderr |
Standard error from the sandbox |
exit |
Sandbox process exited (carries exitCode) |
starting |
Sandbox is starting up |
ready |
Sandbox is ready to accept exec calls |
killed |
Process killed by the host (OOM, timeout, manual stop) |
violation |
A sandbox policy was violated (carries a SandboxViolation) |
SandboxViolation
Section titled “SandboxViolation”| Field | Type | Description |
|---|---|---|
action |
String |
The denied verb (e.g. file-read*, network-outbound) |
target |
String |
Path or host that was the target of the denied operation |
raw |
String? |
Raw log line, useful for debugging |
See also
Section titled “See also”- Sandbox security
- Sandbox policies
- Guardrails
- cc_server CLI: the
--sandboxflag