Skip to content

Sandbox and security

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.

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, /handoff and /goal. When the server sandboxes agents they run inside the sandbox, in a session of their own. Under --sandbox off they 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 bash in 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.

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.

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.

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.

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.

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.

Run agent diagnostics is the single place that states what can be checked by hand.

  • 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