Configure sandbox policies
Whether an agent run is sandboxed is decided on the server, at boot
(--sandbox). The Enable sandboxing toggle and the Backend picker under
Settings → Server → Diagnostics & privacy are preferences stored on your
device. The Sandboxing card’s host detection reports what the server host
can wrap.
Two controls reach a run and this guide covers both: the action rules at
Settings → Workspace → Agent permissions, which decide what an agent may
push, open or reach, and the server’s own --sandbox flag.
What constrains an agent run
Section titled “What constrains an agent run”An agent is held by six things. The first is the OS sandbox and it is the one that is conditional — the other five hold on every host.
| Boundary | What it does |
|---|---|
| The OS sandbox | Seatbelt on macOS, bubblewrap on Linux and WSL2. Wraps the Claude Code CLI, ACP adapters and the harness bash tool. Absent on Windows and on Linux without bwrap and socat, where only the server owner’s runs start |
| Its own worktree | Each conversation gets a copy-on-write checkout. The original checkout is folded into the run as a deny-write path and the sandbox is what enforces it |
| Brokered credentials | The credential broker mints a per-run environment and revokes it at teardown. Its GitHub token can read but not push: a push goes through Control Center, which asks the push rule first |
| Action guardrails | Every mutating tool declares its effect classes and the guard resolves them before the call runs. A prompt with no approver connected is denied |
| Environment sanitisation | ACP and the harness bash tool get a filtered environment. Claude Code through NoSandboxAdapter inherits the host environment |
| The mode’s tool surface | A read-only mode removes the worktree-mutating tools outright and pins the mode’s own output verb so it can still deliver |
Three things stay weaker than they look:
- Only the built-in harness enforces the tool gate, completion contracts and
structural mode rules. The Claude Code adapter does not. Claude
Code in particular is launched with
--dangerously-skip-permissions, because a non-interactiveclaude -pwould otherwise block forever on its own prompt — so Claude’s own read, write and edit calls are neither seen nor gated by Control Center and its bash commands are checked only by a hook that reads the command line. Where the sandbox is on, it is the boundary around them. - The harness’s in-process file tools (read, write, edit, apply patch, search,
find, search_files) run inside the server process, so no sandbox profile constrains them.
Only the
bashtool goes through the sandboxed command runner. Those tools are bounded by their own path confinement plus the action guardrails. - On a host with no backend, only runs the server owner is accountable for
start, and for those the first row does not apply. Everyone else’s runs are
refused. Under
--sandbox offevery member’s runs start without the first row. Either way ACP and the harnessbashtool fall back to environment sanitisation plus the command policy, and Claude Code inherits the host environment throughNoSandboxAdapter. The server says which case you are in on its startup log. Check yours below.
Decide what an agent may push
Section titled “Decide what an agent may push”There is no per-agent switch for git push, GitHub, ticketing or the network. Each is an action rule:
| Rule | Built-in default | What it covers |
|---|---|---|
| Push to a remote | Ask first | Every git push to GitHub, whatever the adapter |
| Open a pull request | Ask first | Control Center’s pull-request tools. gh pr create does not work in a run |
| Update or merge a pull request | Ask first | An agent’s comments on its pull request, edits to its title or description and published reviews, through Control Center’s tools. gh pr comment, gh pr edit, gh pr review, gh pr merge and gh pr close do not work in a run |
| Write to an external tracker | Ask first | Ticket writes through Control Center’s tools and gh issue writes |
| Access the network | Allow | Whether the sandbox has a network at all, and the harness’s web tools |
- Go to Settings → Workspace → Agent permissions
- Pick the scope — Workspace, Agent or Space — and on the rule’s row pick Allow, Ask first or Deny
Branch-constrained push rules, such as one that denies pushes to main, apply
too: see Guardrails.
Checkpoint: ask the agent to push a branch. Under Ask first you get an
approval naming the repo and the refs; under Deny, git prints
! [remote rejected] <ref> (Control Center policy: …).
How each rule reaches the run:
- Push is enforced by what the run holds. Its GitHub token covers the
run’s one repository and cannot push: it can read contents and, when the
accountable member can push, comment on pull requests. Its git configuration
sends every GitHub push to a loopback gateway
on
cc_server, which asks the rule and only then forwards the push on a write token the agent never sees. The gateway forwards only to the worktree’s own repo or a GitHub repo linked to the workspace. This holds for every adapter. - Pull requests and issues from a shell are recognised by command line, in
the harness
bashtool and, through a hook, in Claude Code’sBashtool. An agent that hides the command (a script,eval, a raw API call) gets past this check, but not past the push gateway. - Ticketing keys are never placed in the sandbox. Agents write tickets through Control Center’s MCP tools, which ask the rule.
- Network is resolved once, when the run starts. Deny turns the
sandbox’s network off; Allow and Ask first leave it on, and under
Ask first the harness’s
web_fetchandweb_searchtools still ask per call. While the network is on, GitHub is always on the egress allowlist.
Check whether your agent runs are sandboxed
Section titled “Check whether your agent runs are sandboxed”Two things decide it, both on the server: whether the host offers a backend and
whether --sandbox is on. Check them in that order.
- Go to Settings → Server → Diagnostics & privacy
- Read the Sandboxing card. The Host fact is the machine
cc_serverruns on, not the machine you are looking at. The Backend field lists Native sandbox (Seatbelt on macOS, bubblewrap on Linux and WSL2) or No isolation. The In force fact is this device’s preference, not the wrap the server actually uses. - Read the server’s startup log. It prints exactly one of three lines:
agent sandbox ONplus the backend note: runs are wrappedno OS-native agent sandbox on this hostplus an install hint where there is one: only runs the server owner is accountable for start, unwrapped, and everyone else’s are refusedagent sandbox DISABLED by --sandbox off: every member’s runs start, unwrapped
- The exposure line printed at startup says the same thing in one word:
sandbox=native,sandbox=offorsandbox=unavailable.
GET /healthz does not report sandbox state, so the startup log is the check.
Only the server owner decides to run without a sandbox. To do it for everyone,
start the server with --sandbox off, or set CC_SERVER_SANDBOX=off. Every
member’s agents then run unconfined on that machine, so this is a decision
about everyone who uses the server, made once at boot. The default is on: it
wraps every run when the host has a backend and, when it does not, starts only
the owner’s runs.
Two situations never get a native sandbox wrap. On Windows the native probe
always reports unavailable and there is nothing to install, so only the server
owner’s runs start unless the owner passes --sandbox off. The microvm
backend is separate (interactive terminals and rigs) and is probe-gated on its
own runtime. On Linux and WSL2 both bwrap and socat must be on the
PATH; without them the probe reports unavailable and names the missing
packages, and only the owner’s runs start.
On Linux/WSL2 with bubblewrap installed, the standard policy’s secret-file
globs cannot be enforced for files an agent creates later, so every native run
fails instead of silently ignoring the rules, the owner’s included. A positive
boot probe therefore does not mean a Linux dispatch can start: today a Linux
server runs agents with --sandbox off, or without bubblewrap for the owner
alone. --sandbox off is a deliberate unconfined opt-out, not a substitute
security boundary.
Know what a mode already forbids
Section titled “Know what a mode already forbids”Mode is stored per space and feeds the guardrail resolver as the mode preset layer. Three of the four modes are read-only and a read-only mode refuses twelve effect classes outright:
| Mode | Worktree | Refused by the preset |
|---|---|---|
Agent (chat) |
Writable | Nothing — the built-in defaults apply |
| Plan | Read-only | Delete a file, write outside the worktree, commit, push, open a PR, publish or merge, write to an external tracker, install a package, run a process, change workspace structure, boot or drive an enclosure, run commands on the host |
| Review | Read-only | The same twelve. Not user-selectable — the composer offers only Agent, Plan and Orchestrate |
| Orchestrate | Read-only | The same twelve |
Network access and secret access are deliberately not refused by a read-only mode: research is the point of one.
Require approval before an action runs
Section titled “Require approval before an action runs”Approval is a guardrail decision, not a sandbox setting.
- Go to Settings → Workspace → Agent permissions
- Set the action class to Ask first at the workspace, agent or space scope
An Ask first decision interrupts the run and asks you. With no approver connected it fails closed and the action is denied. See Configure guardrails for the full resolution order.
Troubleshooting
Section titled “Troubleshooting”An agent cannot push and I never denied it
Section titled “An agent cannot push and I never denied it”Read what git printed. Control Center policy: … means a rule denied the push
or an Ask first went unanswered. … is not linked to this workspace means
the push targets a repo that is neither the worktree’s own nor linked to the
workspace. Control Center has no GitHub credential that can push … means no push
token could be minted: install the GitHub App on that repo, or sign in to GitHub.
My agent run was refused with “This server has no sandbox”
Section titled “My agent run was refused with “This server has no sandbox””The run shows Agents need a sandbox on this server 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 server’s host has no OS sandbox, and the run’s accountable person is not the server owner, so nothing was started. For a schedule, webhook or other automation, the accountable person is the one the automation is bound to, not whoever is looking at it.
Only the server owner can change this. On Linux and WSL2 they install
bubblewrap and socat and restart the server (but read the Linux note above
first). On Windows there is no backend to install. The other choice is to
restart the server with --sandbox off, which runs every member’s agents
unconfined on that machine.
The Sandboxing card reports no native sandbox
Section titled “The Sandboxing card reports no native sandbox”Then agent runs on that host are not wrapped by Seatbelt or bubblewrap: only
the server owner’s runs start, and the remaining boundaries are what they
have. On Linux and WSL2, install both missing tools
(sudo apt-get install bubblewrap socat) and restart the server; the startup
log should then say the sandbox is on. On Windows there is no native backend
to install, so tighten the guardrails for the owner’s own runs instead: see
Configure guardrails.
An agent reached a file outside its worktree
Section titled “An agent reached a file outside its worktree”Which tool reached it decides whether this is expected.
The harness’s in-process file tools (read, write, edit, apply patch, search,
find, search_files) run in the server process, so no sandbox profile applies to
them — their bound is their own path confinement plus the guardrails. A bash command or the Claude Code
CLI is wrapped where a backend exists and your registered
checkouts are deny-write inside that wrap in every mode, including their
symlink-resolved spellings (on macOS a path reached through /tmp or
/var/folders resolves under /private and both spellings are denied).
Under --sandbox off, or for the owner’s own runs on a host with no backend, none
of that applies. Either way, guardrails can refuse
Write outside the worktree outright.
Related guides
Section titled “Related guides”- Configure guardrails
- Create and configure an agent
- Diagnose an agent
- Sandbox backends
- cc_server CLI: the
--sandboxflag