Sandbox and security
Why isolation matters here
Section titled “Why isolation matters here”An agent reads files, runs shell commands and calls external APIs on your behalf. The failure you care about is rarely malice — it is an agent that misreads a path and rewrites your working checkout, or one that pushes a branch you had not finished reviewing. So the question the product has to answer is not “is the agent trustworthy” but “what is the blast radius when it is wrong”.
Control Center answers that in layers and the layers are independent on purpose. If one is missing, the others still hold. That matters, because the outermost layer — the OS sandbox — is the only conditional one: it depends on the host offering a backend and on Windows no host does. Where it is missing, the server does not quietly run everyone’s agents without it.
Agents on a host without a sandbox
Section titled “Agents on a host without a sandbox”The server decides once at boot how agents run on its machine, and keeps that decision until it restarts:
- Sandboxed. The host has a backend and the sandbox is on. Every run is wrapped.
- Off. The server owner started the server with
--sandbox off. Every member’s agents run unconfined on this machine. That is the owner’s choice for everyone who uses the server, not a setting for one run. - Unavailable. The sandbox is on but the host has no backend. A run starts only when the person accountable for it is the server owner: the person who asked for it, or for a schedule, webhook or other automation, the person it is bound to. Anyone else’s run is refused before a credential is minted or a process starts, with “This server has no sandbox, so only its owner can run agents here. The owner can install the sandbox or turn sandboxing off for everyone.”
The reason is ownership of the machine. An unconfined agent can do whatever the server’s user account can do, so only the person who owns that account runs one, unless they decide otherwise for everybody. A Windows server is always in the unavailable case. Linux has its own wrinkle, covered in the sandbox backends reference: native dispatch currently fails closed there even with bubblewrap installed.
The same rule covers the smaller things that start a process for you:
- Quick helpers that run through an ACP CLI: conversation titles,
/btw,/handoffand/goal. When the server sandboxes agents they run inside the sandbox, in a session of their own. Under--sandbox offthey run unconfined. With no sandbox available they run only for requests the server owner is accountable for; for anyone else they are skipped, so no title is generated and a side question reports that the Content synthesizer has no working runner. Helpers that start no tool are not affected. - A pull request’s golden tests in Review Studio’s visual check follow the same rule.
- Tool processes and
bashin a run never fall back to the host. If the server is set to sandbox agents but has no sandbox to give a run, they are refused.
What actually constrains an agent
Section titled “What actually constrains an agent”Five things bound an agent run on every host, sandbox or no sandbox. None of them is a kernel boundary; all of them are real. Where the host offers a backend the OS sandbox sits above them and “What the sandbox adds and where it stops” below covers what that changes.
Its own copy-on-write worktree. Every conversation provisions its own
checkout of each linked repo, cloned copy-on-write through the bundled rift
native rather than copied byte by byte, so isolation is cheap enough to be the
default. The registered repository you added to the workspace is not the
directory the agent works in — two conversations touching the same repo cannot
see each other’s edits and neither is editing your checkout.
The grain is worth being precise about: the worktree is per conversation, not
per agent. Two agents in the same conversation get distinct overlay working
directories that share that conversation’s repos/ — which is the point,
since they are collaborating on one change — while their private agent
directories stay separate. Copy-on-write is the only backend wherever rift
ships: a filesystem that cannot reflink, or a data dir on a different volume
from the repo, fails the provision rather than falling back. Windows is the
exception — there is no copy-on-write backend there, so git worktree is the
backend, not a silent degradation.
Path confinement in the built-in harness’s file tools. The harness’s read,
write, edit, apply_patch, search, find and search_files tools
resolve every path against the run’s working directory plus shared roots — the
conversation’s repos/ directory, where the worktrees live, and the space’s
attachments dir when it exists — and refuse anything that lands outside.
Absolute paths are accepted only if they were already inside. A symlink inside
the worktree pointing out of it is resolved and refused too. This is why an
agent cannot write to ~/.ssh even with no sandbox in the picture.
The mode’s tool surface. A conversation’s mode
decides which tools are materialised for the run at all. In the read-only modes
(plan, review, orchestrate) the mutating tools are simply not in the
registry and the shell command policy for those modes denies every mutating
command outright — git commit, git push, npm install, docker and the
rest — rather than prompting for them. A tool that is not present cannot be
called, which is a stronger guarantee than a tool that is present and gated.
The unified action guardrails. Every mutating tool declares the effect
classes it can produce and the policy engine resolves each one to allow,
prompt, or deny before the call runs. A prompt with no approver connected
resolves to denied — a question nobody can answer is never a yes. See
Guardrails for the resolution model.
Brokered credentials and a sanitised environment. Credentials are minted
per launch and revoked when the run ends, and the GitHub token a run holds can
read but cannot push — see “Pushes go through Control Center” below. ACP, harness bash and Claude Code under the native wrap get an
environment stripped of the dynamic-linker and interpreter injection vectors
(LD_PRELOAD, DYLD_INSERT_LIBRARIES, NODE_OPTIONS, GIT_SSH_COMMAND and
their kin) before the process starts. Claude Code through NoSandboxAdapter
inherits the host environment.
Where those bounds thin out
Section titled “Where those bounds thin out”The harness’s file tools run in the server process, not in a child process, so
no sandbox profile could constrain them even if one were attached — only bash
goes through the sandboxed command runner. Their confinement is the path check
described above and that check is therefore load-bearing rather than a second
line of defence.
The bash tool is the other place to be precise. Its commands are evaluated
against the mode’s command policy and then spawned with a sanitised environment
and the worktree as its working directory. Where a backend exists that spawn is
wrapped, so the sandbox is what stops a shell command from writing outside the
worktree; where none does (every run under --sandbox off, and the owner’s
own runs on Windows or on Linux without bwrap and socat) the command
policy is the only thing between the command and the rest of the disk.
In chat mode the policy hard-denies a fixed list (privilege escalation,
system and disk destruction, container and namespace escape) and prompts on
remote-state mutations (git push, gh pr create, package publishes and
installs). Anything on neither list runs. Pipelines, chains and subshells are
parsed and each sub-command evaluated separately, with the most restrictive
decision winning.
Claude Code, when used as an adapter, is the case where the sandbox carries the
most weight. Control Center launches it with --dangerously-skip-permissions,
because a non-interactive claude -p would otherwise block forever on its own
approval prompt. Its read, write and edit calls happen inside its own process
and Control Center never sees them. Its Bash calls are sent, before they run,
to a hook on the server that classifies the command line and asks the matching
rule, and the mcp__* tools Control Center serves are gated as usual. Where a backend
exists, those unseen calls still happen inside the sandbox wrap, so the OS is
the boundary around them. Where none does, nothing is. Each adapter states this
in its enforcement matrix — see the adapter honesty
matrix.
Pushes go through Control Center
Section titled “Pushes go through Control Center”There are no per-agent permission flags. Whether an agent may commit, push, open a pull request, write to a tracker or reach the network is the guardrails’ call — allow, ask first or deny — and the same rules apply whichever adapter runs the agent.
A push is the action that has to hold even against an agent working around a
rule, so it is enforced by what the agent holds rather than by what it runs.
A run holds no forge token when it starts, and its git never gets one. When its gh needs one,
Control Center hands it a token for one GitHub repository the run works on, minted from
the workspace’s GitHub App, the server’s own app or Control Center Connect. It
only reads: it cannot push, comment or edit. The run’s git configuration rewrites every GitHub push URL
(https://github.com/, git@github.com:, ssh://git@github.com/) to the
agent run gateway, a loopback endpoint on cc_server. The gateway reads
which refs the push updates, asks the Push to a remote rule — so a
branch-constrained rule such as “deny pushes to main” applies — and only then
forwards the push to GitHub on a write token it mints for that purpose and
never hands to the agent. A refused push shows up in git’s own output:
! [remote rejected] main -> main (Control Center policy: …)The gateway forwards pushes only to the worktree’s own repo or a GitHub repo linked to the workspace. Fetches go through the gateway too, on GitHub, GitLab and Bitbucket: it fetches the repositories the run works on with a credential it keeps and the run never sees. On GitLab and Bitbucket that is your own token when you asked for the run, and the repository’s automation token when nobody did. A fetch asks no one, and only a deny on Access the network refuses it.
Other shell commands meet a softer gate. The harness bash tool, and Claude
Code’s Bash tool through a hook, classify each command line and ask the rule
it falls under: git commit, merge, rebase, cherry-pick, revert and
am are Create a commit; gh pr create is Open a pull request;
gh pr merge, review, comment and close are Update or merge a pull request; gh issue create, edit, comment and close are Write to an
external tracker; package installs are Install a package; curl and
wget are Access the network. Writing to GitHub from the shell is the exception: gh pr create, gh pr comment,
gh pr edit, gh pr merge and gh issue writes do not work in a run, whose token
only reads, and the agent is pointed to Control Center’s tools, which ask these
rules. This recognises the conventional spelling of
an action, and an agent determined to hide one (eval, a script file, a raw
API call) can. Pushes do not depend on it.
Every GitHub token a run receives is bounded twice: to one repository, and to what the accountable member (the one who asked, else the workspace owner) can do there. There is no fallback credential. When no token can be minted, the command that asked for it says why.
No ticketing API key is placed in a sandbox. Agents write tickets through Control Center’s MCP tools, which ask Write to an external tracker.
The Access the network rule is read once, when the run starts. A sandbox’s
network is either on or off, so a deny turns it off while allow and ask first
leave it on; the harness’s web_fetch and web_search tools still ask per
call. The run’s credential handles are released when it tears down. The
tokens behind them are shared per member and repository and expire within
about an hour; a member signing out of GitHub or leaving the workspace drops
every token minted on their behalf at once.
Repositories an agent can only read
Section titled “Repositories an agent can only read”An agent run may change only the checkouts of repositories that the person it acts for holds the write grant on. Workspace admins hold it on every linked repository. A run nobody asked for, such as a schedule or another automation, is judged by the same accountable person its automation token is bounded by.
In a space with a repository that person can only read, the agent can still read and search that repository, but it cannot change its files. Its file tools refuse with a message that starts <repo> is read-only for this run and says that changing the checkout takes the write grant, which the person the run acts for does not hold, and that a workspace admin can grant it. Inside a sandbox the checkout is read-only for every process, so a shell command that writes there fails with “Operation not permitted”. That includes git commit and a build or test that writes its output inside the checkout. Repositories the person can write behave as usual, so admins, and anyone with write access to every repository of the space, see no difference.
This is decided once, when the run starts. A grant change takes effect on the agent’s next run, and so does a repository added to the space during a run.
Where the server owner has turned the sandbox off, only the agent’s own file tools and Claude Code’s write tools are refused, and shell commands can still change the checkout. Nothing can be pushed without the write grant either way, because every push is checked against it. Which processes the sandbox confines on each platform is in Sandbox backends.
What the sandbox adds and where it stops
Section titled “What the sandbox adds and where it stops”The SandboxBackend enum has three values — native (Seatbelt on macOS,
bubblewrap on Linux and WSL2), none, and microvm. Agent command wrapping
uses only the first two: microvm is the enclosed-VM backend for interactive
terminals and rigs, not a silent upgrade of a bash wrap. Understanding the
native shape explains what you gain where one is attached and what it was never
going to give you.
cc_server probes the host once at boot and where a backend answers it feeds
both of the seams the dispatch path has, because the transports do not share
one. The first (SandboxPort) wraps the Claude Code CLI. The second
(SandboxManager) wraps ACP adapters and the built-in harness’s bash tool.
Feeding only one would leave the others spawning unwrapped, which is what used
to happen. Under --sandbox off they all spawn unwrapped; on a host with no
backend only the owner’s runs start, also unwrapped. The server says which
case you are in on its startup line. ACP
and harness bash still sanitise the environment; Claude Code through
NoSandboxAdapter inherits the host environment.
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. Only the person who opened a terminal can type into it, read it or close it.
On Linux, bubblewrap builds a mount namespace, so the agent genuinely sees
only what was bound into it. On macOS, sandbox-exec applies a Seatbelt
profile that is permissive by default — a fully deny-by-default profile
makes an interactive shell unusable, because the number of dyld, XPC and Mach
calls to enumerate is impractical. The macOS profile therefore starts from
(allow default) and carves out denies: reads of secret paths, a write policy
reset to deny with explicit allows on top, unlink-blocking on every denied path
and its ancestors so a rename cannot bypass a write-deny, exec denies for
always-dangerous binaries and for anything copied into a writable directory and
network restricted to the loopback proxy ports plus DNS. Toolchain installs under
your home (corepack’s pnpm, node version managers, Playwright browsers, rustup,
fvm, uv and similar) stay runnable inside that exec block, so agents can use
them without workarounds. The always-dangerous denies still apply inside them.
Each session also gets its own private TMPDIR. It is the only temp directory
where the agent may run programs it built or open Unix sockets.
Two more protections apply in every mode. A sandbox cannot add, replace,
delete or rename a command in the folders the server runs programs from
(every folder on its PATH and the usual per-user tool folders), so a
sandboxed run cannot plant a program the server later starts outside the
sandbox. Global installs and default-version switches from inside a run
therefore fail with “Operation not permitted”, while project-local installs
and npx-style runs keep working; install global tools on the server itself
and restart it. And every home path a sandbox cannot read it cannot write
either, with the server user’s shell and session start-up files never
writable. Details and platform limits are in
The server’s command folders.
A run’s tool sandboxes belong to that run and are released when it ends. Language servers start fresh with each sandboxed run. A debug session keeps its sandbox across turns until the session ends, for at most 30 minutes.
The practical consequence: on Linux the agent’s view of the filesystem is narrowed; on macOS the agent can still read most of the host and your registered checkouts are protected by explicit write and rename denials rather than by invisibility. Both are namespace-level isolation, not a kernel security boundary — the backends say so in their own capability notes.
The bind-mount set is where the cross-agent boundary is drawn. Overlay dispatch
(Claude Code and ACP) mounts up to four paths, resolved per run: the agent’s
overlay working directory read-write, the agent’s config directory read-only,
the conversation’s shared repos/ directory read-write when it exists, and the
space’s attachments directory read-only when it exists. A sibling agent’s
directory is never mounted. The harness bash wrap is narrower: it bind-mounts
only the run’s working directory. This is the same shape the harness’s
in-process path check enforces in software, so the two agree — but only the
path check covers the harness’s own file tools, which never reach a mount
namespace at all.
Your registered checkouts join the deny-write set on top of that, in every mode
and on all three of the wrapped paths (Claude Code, ACP, harness bash), and
each rule is emitted in both its literal and its symlink-resolved spelling. The
second spelling is not a nicety:
the kernel matches a deny rule
against the resolved path and macOS makes resolution the common case rather
than the exotic one — /tmp is really /private/tmp, /var/folders/… is
really /private/var/folders/… — so a checkout reached through either would
have been writable while the profile appeared to forbid it.
Network, under a sandbox, is a per-session domain allowlist enforced by
in-process loopback proxies. Egress is default-deny: with the network off, the
proxies still start but their allowlist is empty, so every outbound connection
is refused. With it on, the resolver builds the allowlist from a curated
baseline — LLM API providers, git hosting, package registries, the model
catalogue — plus GitHub’s domains and matches every connection’s target host
against it. Wildcards work (*.example.com matches subdomains, not the apex). A
separate always-denied list wins over the allowlist and covers cloud metadata
endpoints and telemetry sinks. What is not configurable is the list itself:
the spec carries an egressAllowlist field for extra domains, but nothing in
the dispatch path populates it, so in practice every run gets the baseline plus
GitHub and nothing more.
Denials, on macOS, are observable: a monitor taps the system log for Sandbox
denials, filters known noise, deduplicates retry storms and surfaces each as a
SandboxViolation naming what was attempted and what was blocked. On Linux the wrap path parses stderr for EPERM, Operation not permitted
and Permission denied and emits the same event type — there is no system-log
tap. Those arrive on the run’s own event stream, so a denied syscall shows up in
the transcript rather than only in a log. The telemetry only exists while a
native sandbox is actually wrapping the process — on a host with no backend
there is nothing to observe. It is also unrelated to the guardrails: a
violation comes from a denied syscall, never from a rule lookup.
Confirmations come from the guardrails, not the sandbox
Section titled “Confirmations come from the guardrails, not the sandbox”The sandbox has no approval path. It launches, executes, emits events and tears down; there is nowhere in it for a human to answer a question. When you see a confirmation in a space — approve this push, approve this delete — it was raised by the guardrail engine (or the harness’s command policy) before the action reached the runtime at all.
This ordering is deliberate. An approval that happened after the syscall would be an audit record, not a gate. It is also why the fail-closed rule lives in the guardrails: with no approver connected, the decision is made before anything runs and it is a denial.
Diagnostics
Section titled “Diagnostics”Run agent diagnostics is the single place that states what can be checked by hand.
Related concepts
Section titled “Related concepts”- Rigs and enclosures: the step above the sandbox — when the work needs a whole disposable machine with a kernel boundary, not a wrapped process
- Guardrails: the policy layer above the OS floor and where approvals actually come from
- Agent dispatch lifecycle: where isolation fits in the dispatch flow
- Modes: how a mode narrows the tool surface and the command policy
- Sandbox backends reference: the backends and their configuration
Related guides
Section titled “Related guides”- Configure sandbox policies: action rules, push enforcement and filesystem posture
- Run agent diagnostics: what the diagnostic checks cover