Skip to content

Sandbox backends

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.

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.

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/Keychains and 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-unlink is denied on every denied path and its ancestors, so a rename cannot bypass a write-deny
  • Process: process-exec denies for the always-dangerous binaries, plus a block on executing anything from a writable directory. Known toolchain install trees under your home (corepack, npx and pnpm dlx caches, 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 private TMPDIR under /private/tmp, where programs it builds (a go test binary, 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 PATH entry and the usual per-user tool folders such as ~/.local/bin, with version-manager links like ~/fvm/default resolved) 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

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 socat Unix-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:

  • bubblewrap and socat installed (sudo apt-get install bubblewrap socat on 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 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, and cargo install, go install or dart pub global activate when their bin folder is on the server’s PATH.
  • 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.

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.

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. $HOME and the session’s working directory are writable, the network is open, and ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh and ~/Library/Keychains are 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, /tmp and the parts of $HOME an 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.
  • microvm asked for explicitly on a host with no rig service fails instead of falling back. A microvm default on such a host steps down to native and 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.

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.1 inside the cc_server process, 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_COMMAND routes 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.com matches any subdomain (including a.b.example.com) but not the apex itself; a middle-label bedrock.*.amazonaws.com matches exactly one label (bedrock.us-east-1.amazonaws.com, not bedrock.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), plus SandboxSpec.egressAllowlist. The dispatch path never passes extra egressAllowlist entries, 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: false still 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.

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.

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

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.)
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
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)
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