Sandboxing¶
tclaude can confine an agent inside an operating-system sandbox: a wall around the harness process that decides which directories it can read or write, which network destinations it can reach, which Unix sockets it can connect to, and how much CPU, memory and how many processes its whole process tree may consume. The policy is authored once, as a harness-neutral sandbox profile, and enforced by whichever backend can faithfully carry it — or the launch is refused.
Three ideas carry this page:
- A profile is what you author: a JSON capability bundle.
--sandboxis the harness's own sandbox mode — a per-harness setting.--sandbox-implis who enforces confinement — the harness itself, tclaude’s built-in sandbox, a resource-only cgroup, or nobody.
Egress filtering has its own page (Network filtering), and credential-less workflows that make strict profiles livable have theirs (Credential proxies).
Start here¶
By default, a new install runs agents inside tclaude's own sandbox. If that can't run on your host, agents won't start, and Doctor tells you why.
To confine an agent:
- Create a sandbox profile in the library, or use
tclaude agent sandbox-profiles. - Pick it under Sandbox profile in the spawn dialog, or set it for a group with 🛡.
- Check the result: the row shows 🔒, or ⚠ if some rules are enforced more
loosely than configured. Its tooltip lists what applies, and
tclaude agent sandbox-profiles planshows the plan for a profile.
When something is blocked, one of three things happens: the launch is refused with a reason, it launches with a notice, or a path is simply masked inside the sandbox. See Symptom → cause.
To get unstuck:
- Give the profile a rule for just that path.
- If the refusal is about network rules or resource limits, tick Allow launch with unenforced rules in the spawn dialog, for one fresh launch. It doesn't help with masked or protected paths.
- On a running agent, use ⚠ restart without sandbox in its ⚙ menu, or click the sandbox badge. 🔒 restore sandbox + restart puts it back.
tclaude agent debug-export <agent>shows what really ran, as does export debug info in the agent's ⚙ menu.
The rest of this page is reference.
Who enforces: --sandbox-impl¶
The sandbox implementation is selected at spawn and recorded with the conversation — it is durable relaunch intent, so a flagless resume uses the same layer. The values:
harness-builtin— the harness confines itself with its own OS sandbox. Valid as an explicit pin only for harnesses that really own one: Claude Code (bubblewrap on Linux, Seatbelt on macOS), Codex, and Gemini CLI on macOS (its Seatbelt modeseatbelt). OpenCode refuses the pin — its access control is a command filter, not confinement — and Copilot's descriptor declares no built-in OS sandbox. pi has no sandbox of its own; tclaude's sandbox is its only boundary. Leaving the implementation unset is different from pinningharness-builtin: unset falls through the precedence chain and preserves each harness's historical behavior (for OpenCode, the command filter plus an explicit no-confinement warning).- tclaude’s built-in sandbox (
tclaude-layer) — wraps the tool-executing harness process in its own sandbox: bubblewrap mount/IPC/cgroup/PID (and optionally network) namespaces on Linux, Seatbelt (sandbox-exec) on macOS. The harness's own OS sandbox is forced off inside it (Claude Code modeoff, Codexdanger-full-access, Gemini CLIoffviaGEMINI_SANDBOX=false; Copilot has no off-flag tclaude can set, so its configuration is verified instead and an unverifiable posture refuses; pi has no sandbox to turn off). Supported for Claude Code, Codex, OpenCode, Copilot, Gemini CLI, pi and shell, on Linux and macOS. For OpenCode the wrapped process is the agentd-ownedopencode serveexecutor; the attach pane stays outside. Requiresbwrapand working unprivileged user namespaces on Linux; a missing capability refuses the launch — never a silent fallback — from whichever tier selected the layer. Thebwrapfound onPATHmust also pass the trust walk described under An untrustedbwrap. On Linux the layer also creates and joins a per-launch cgroup even with noresource_limitsauthored: tclaude already owns and forks this workload, so the same accountingresource-onlygives (memory.peak,cpu.stat, host-OOM attribution, one kill handle for the whole tree) comes along. That boundary is a bonus, not the posture — a host with no delegated cgroup gets aresource_cgroup_unavailablenotice and the wall it asked for, whereresource-onlyrefuses. An authored ceiling still fails closed. resource-only(Linux only) — no access confinement at all: the harness runs in its native no-confinement mode, but every launch creates and joins a per-launch cgroup. Withresource_limitsauthored you get CPU, memory and PID ceilings; without them you still get per-agent accounting (memory.peak,cpu.stat), host-OOM attribution (resource_limit_oomexit reason), and a kill handle for everything the agent started. The profile chain still resolves — it carries the limits — and its access rules are recorded but not enforced, disclosed with anot_enforcednotice. Remappedmount_pathrules, rows naming a single file, and non-Linux hosts refuse. A fresh launch that cannot create its cgroup refuses; a relaunch of a ceiling-free boundary degrades with aresource_cgroup_unavailablenotice instead (ceilings always fail closed).off— the cross-harness explicit opt-out: each harness's native no-confinement posture (Claude Code and OpenCodeoff, Codexdanger-full-access), composed profile policy omitted, resource limits refused. Because it is recorded, a group or global default cannot silently re-sandbox the conversation on a later relaunch.
The former stacked value (tclaude's sandbox with the harness's own sandbox
nested inside it) has been removed; conversations, profiles, and templates
that recorded it resume as tclaude’s built-in sandbox (tclaude-layer).
Select it wherever agents are spawned: tclaude session new --sandbox-impl,
tclaude agent spawn --sandbox-impl, a spawn profile's Sandbox field, or the
dashboard spawn dialog — which presents the implementation choice first and
shows a "\<Harness> sandbox mode" row only after you pick the harness's
built-in sandbox. Precedence, highest first: explicit flag or dialog selection,
then --profile, then the group's default spawn profile, then the global
default profile, then the install default (below), then the harness default.
The install default¶
The install default is what an agent spawn gets when nothing above chooses an implementation. It has three states:
tclaude-layer— new agents use tclaude's own sandbox.tclaude setuprecords this on a new install (a database this tclaude version created).harness— each harness's own sandbox stays in charge, exactly the behavior before the install default existed.- undecided — behaves like
harness. An install that already had history when it upgraded stays here, so an upgrade never changes how the next agent is confined; the dashboard's Diagnostics › Doctor view asks the operator to choose.
tclaude agent sandbox default show
tclaude agent sandbox default set tclaude-layer # or: harness
tclaude agent sandbox default clear # back to undecided
set and clear need sandbox-profiles.manage. The install default applies to
new agent spawns only: existing agents relaunch, reincarnate and clone under the
implementation recorded when they were spawned, and a human's own
tclaude/tclaude session new terminal launch keeps the harness's posture.
On a host that cannot run tclaude's sandbox (no bwrap, or unprivileged user
namespaces disabled) a spawn that gets tclaude-layer from the install default
is still refused rather than silently unconfined; the refusal names both ways
out, and Diagnostics › Doctor shows the install command.
For OpenCode, Copilot and pi, which own no OS sandbox of their own, the old
"unset" posture (for OpenCode, its command filter) has no per-spawn spelling
once the install default is tclaude-layer: harness-builtin is refused for
them and off drops the filter too. Set the install default to harness to
get it back.
Reassigning an existing agent¶
tclaude agent sandbox show|set (formerly sandbox-impl, which still works
but is deprecated, as is its /v1/agent/{selector}/sandbox-impl route in
favour of /v1/agent/{selector}/sandbox) takes a positional selector (there is no
self form and no --target). A stopped agent is assigned and left stopped
(wake it to apply). A running agent is refused unless --restart is given:
then, once every check below has passed, the agent — which must be fully
idle — is stopped, assigned, and resumed in the same conversation, carrying
any attached terminal across. The assignment is validated against the chain
the relaunch will resolve, and probes cgroup
creation for implementations that cannot launch without one. It needs the
agent.sandbox-impl permission, which group ownership deliberately does not
confer and which is not granted by default. The dashboard equivalent is
🧩 sandbox implementation / profile… in the agent's row menu, which restarts a
running agent the same way. A harness mode that was
merely derived from the old implementation is not carried forward; the harness
default is recorded instead unless --sandbox pins one.
Assigning tclaude's sandbox to an OpenCode agent with no private state moves its conversation there, because the sandboxed server cannot read the shared store. The conversation keeps its id and its spend, along with any subagent sessions under it. tclaude checks that the copy reads back the same before it records the assignment, then deletes the shared copy. If the copy fails, the agent stays as it was and the assignment reports why. A running agent is stopped first, as for any assignment with a restart.
The move carries what opencode export carries, so the agent's todo list is
deleted with the shared copy, and the assignment's result says so. Older
conversations from before a reincarnation stay in the shared store.
Assigning any other implementation moves the conversation back, because those read the shared store. It works the same way and has the same limits: the conversation keeps its id, the copy is checked before the assignment is recorded, and the todo list is deleted. Every conversation in the agent's private state moves, including any from before a reincarnation, and the private state is then deleted. Agents outside tclaude's sandbox can read the shared store, so these conversations are no longer private, and the assignment's result says so. Assigning tclaude's sandbox again moves only the current conversation back.
This move asks first. Before anything stops or moves, the dashboard shows how many
conversations will be exposed, that agents outside tclaude's sandbox can read them
once moved, and that todo lists are deleted, and you confirm it there. On the
command line sandbox set refuses with the same facts unless you pass
--yes. An agent that asks with --ask-human gets you a popup with the same
facts. Nothing asks when the agent has no private state. Private conversation
storage is something only OpenCode has here: other harnesses keep conversations
in a state root shared per harness, so moving out puts this agent where those
already are.
If a conversation cannot move, the assignment is refused and the agent stays as it was. One reason is that the shared store already holds a different conversation under the same id. To change that agent's posture, export it and import it under the posture you want.
The dashboard's restart without sandbox is refused while the conversation is in private state, because a one-off restart should not move it. Assign the implementation you want instead.
Changing an existing agent's sandbox profile¶
tclaude agent sandbox set <agent> --sandbox-profile strict --restart
tclaude agent sandbox set <agent> --no-sandbox-profile
tclaude agent sandbox set <agent> tclaude-layer --sandbox-profile strict
The same assignment replaces the agent's explicit sandbox profile (the
one its spawn named with --sandbox-profile), alone or together with the
implementation, in one restart. The global and group tiers are not the
agent's to change here: they keep following the workspace and group
assignments. The same rules apply as for the implementation: a stopped agent
is assigned and left stopped, a running one needs --restart, the
agent.sandbox-impl permission is required, and every launch gate is run now
against the chain the new profile gives, so a profile the agent's posture
cannot carry is refused here rather than at wake time. The agent's explicit
harness-config posture, group environment and deny overlay must still apply
over the new chain.
The change is recorded beside the policy stored at the last launch, not in
it. show reports the profile as assigned until a launch applies it. If the
relaunch cannot use the new profile (it was deleted meanwhile, say), it falls
back to the stored policy with a warning, as for any unusable profile, and
the assignment stays pending for the launch after. Under a relaunch policy
that reuses stored profile contents, a changed profile is re-read, exactly as
a changed group assignment is. Choosing the profile the agent last launched
under again cancels a pending change.
An agent whose launches omit sandbox profiles (spawned with
--omit-sandbox-profiles, or under a mode that cannot carry them) takes them
back the same way: assigning a profile, or --no-sandbox-profile, lifts the
omission, and the next launch applies the global, group and explicit tiers
again. The implementation the agent relaunches under must be able to carry
them, so an agent on off needs another implementation in the same
assignment. --omit-sandbox-profiles goes the other way and makes every
launch of the agent omit all tiers; it is refused for an agent that carries a
deny overlay. In the dashboard,
the same dialog has a Sandbox profile picker beside the implementations,
and shows the global and group profiles that also apply. It starts on keep
current, which changes nothing. Default removes the agent's explicit
profile, so it resolves like a spawn that names none: the global profile,
then the group's (--no-sandbox-profile on the command line). None omits every tclaude sandbox profile
(--omit-sandbox-profiles).
A peer with restricted trust cannot change a profile: its sandbox requests carry only an implementation.
Imported agents¶
Imports take the receiver's posture, resolved the way a spawn resolves it, and an unmeetable one is refused rather than downgraded. See Landing posture.
The harness's own mode: --sandbox¶
--sandbox on tclaude session new sets the harness-native sandbox mode. It
is per harness, persisted per conversation, and orthogonal to who enforces:
- Claude Code:
inherit(default — thesettings.jsonposture is left untouched, which is what the unsandboxed-autonomy warning is about) |on(force the OS sandbox via a settings overlay; outranked only by managed policy) |off. - Codex:
tclaude-agent(the setup-managed profile — workspace-write plus the agentd socket plus denies on tclaude's private state; the daemon spawn default) |workspace-write|read-only|danger-full-access. - Copilot:
inherit|offonly — deliberately noon, because tclaude has no lever to enable Copilot's sandbox. - OpenCode: no built-in OS sandbox; tclaude’s sandbox is its real confinement mode.
Under tclaude’s sandbox the mode is derived (forced off/danger inside the wall), not an operator escape hatch.
The profile model¶
A sandbox profile is an operator-authored, harness-neutral JSON document —
there is no YAML form. It is Kubernetes-flavored in two concrete ways: memory
limits accept k8s-like quantities (4GB, 1.5GiB, 512MiB; decimal K/M/G/T
and binary Ki/Mi/Gi/Ti, case-insensitive), and mount_path is an explicit
Kubernetes-style volume-mount projection.
The axes:
filesystem— rows of{path, access, mount_path?}withaccessone ofread|write|deny. A row names a directory or a single regular file; anything else (a socket, device node, or FIFO) is rejected.~expands to the daemon's home; paths are symlink-resolved and case/NFC-canonicalized, and duplicate spellings of one physical directory fold into a single row with deny > write > read. Missing paths are retained with a warning and skipped at launch — tclaude never creates operator-authored host paths.- File rows —
{"path": "~/.gitconfig", "access": "read"}reopens exactly that one dotfile beneath a denied Home, without handing over the rest of the directory it lives in. A saved file row records"kind": "file", and a launch refuses if that pathname now holds a directory: the path would re-resolve cleanly and bind the whole replacement tree, which is wider authority than was authored. The record travels with the rule rather than being re-derived, so it survives the path going missing and coming back. (The reverse — a directory row whose path became a file — is a narrowing and is allowed. Directory rows stay unstamped, so existing profiles are unchanged.) Two further limits, both refusals rather than silent degradations:denymay not name a file. Hiding a directory is a mount of an empty tmpfs over it, and no primitive makes a single file absent — every candidate substitutes content instead of removing the name. Deny the containing directory and reopen the entries that must stay reachable.- Enforcement needs tclaude’s sandbox on Linux. Binding one file requires a
mount namespace whose whole boundary tclaude owns. Seatbelt,
harness-builtin, andresource-only/offall refuse withunsupported_sandbox_profile_file_grant.
- Carve-outs work in both directions. A narrower row shadows a broader one:
a narrow
writereopens beneath adeny, and a narrowdenyhides beneath an allow. This most-specific-wins shape is the whole strictness mechanism — see below. mount_path— aread/writerow may project its host path at a different sandbox path ({"path": "/srv/corpus-v3", "access": "read", "mount_path": "/data"}), whether that host path is a directory or a file.denyrows may not carry one (a deny hides a path, it never projects). Two host paths cannot claim one guest path; one host path at several guest paths is fine; a host path whose most specific rule is a deny may not be remapped. Ordering and most-specific-wins evaluate in guest-path space. Under an inherited filesystem root the mount point must already exist on the host and be the same kind as the source — there the sandbox root is the host root, so bubblewrap has nowhere to create one; a constructed root creates it. Enforcement needs a real mount namespace, so it works only under tclaude’s sandbox on Linux. Seatbelt (a path filter, not a mount namespace) andharness-builtinrefuse the launch withunsupported_sandbox_profile_mount_pathrather than falling back to the host path.tmpfs— rows of{path, size?}mounting a temporary filesystem inside the sandbox:{"path": "/scratch", "size": "512MiB"}. This is the one thing afilesystemrow cannot express — writable space backed by no host directory at all, which vanishes when the launch ends. The dashboard editor has a Temporary filesystems section for it, beside Filesystem.pathis a sandbox path, so it is validated syntactically likemount_pathand never resolved against the host;sizetakes the same k8s-like quantities as a memory limit and, when omitted, gets the kernel's tmpfs default of half of RAM — worth setting, because an agent that fills an uncapped tmpfs is consuming host memory. A tmpfs takes part in ordinary most-specific-wins ordering: it shadows what was at its path, and a narrowerread/writerow still lands on top of it. What it may not do is claim a path afilesystemrow already claims (that is a conflict of intent, not a shadow), intersect a protected root, shadow the agentd socket, or cover a launch-required directory such as the workspace or the harness state root — each is a refusal naming the row. Under an inherited filesystem root the mount point must already exist on the host, for the same reasonmount_pathneeds one;filesystem_root: separateis usually the answer for a path like/scratch. Enforcement needs a mount namespace whose whole boundary tclaude owns, so it works only with tclaude’s sandbox on Linux — Seatbelt,harness-builtin, andresource-only/offall refuse withunsupported_sandbox_profile_tmpfs.harness_config—read|write, omitted meaning the default read-only floor over the harness's own config surface. See The harness-config floor below. Composes strictest-wins: an explicitreadanywhere in the chain cannot be widened back towriteby a later scope or include.environment—{name, value}pairs, non-secret. Reserved names are refused:HOME,PATH,SHELL,TMPDIR,CLAUDE_CONFIG_DIR,XDG_CONFIG_HOME,TMUXand friends, plus theTCLAUDE_,CLAUDE_CODE_,CODEX_,LD_, andDYLD_prefixes — with the single exceptionTCLAUDE_OFFLINE_MODEL.agent_directories— environment-variable names bound to tclaude-materialized private per-agent directories.filesystem_root—inheritprefers the read-only host root,separaterequests the minimal constructed root even with open network, omitted means automatic derivation. Composes monotonically:separateanywhere in the chain wins, andinheritcannot weaken a rule whose enforcement itself requires a constructed root.network— an authoredbaselineofinherit|allow|deny, allow/deny rows, packs, and anamespaceselector (the legacynetwork_access: internet|nonespelling is still accepted). The composed result resolves to an open, closed, or list-filtered launch. Covered on the network-filtering page. Linux packet-filtered launches present the harness as the invoking numeric UID/GID.unix_sockets—mode: open|closed|listpluspath/path_globentries (**is refused). The agentd socket is a non-removable floor. Authoring this axis on an otherwise host-open profile switches the launch to a constructed root; see Network filtering.resource_limits—memory→ cgroupmemory.max,cpu(cores ≥ 0.01) →cpu.maxat a 100 ms period, andpids(a whole count ≥ 1) →pids.max; Linux cgroup v2, whole workload tree, orthogonal to confinement, works with any non-offimplementation. The PID ceiling bounds an exhaustion the other two do not — a fork bomb, an unboundedmake -j, a tool loop leaking processes — and needs the delegatedpidscontroller, which the documentedDelegate=cpu memorydoes not carry: author one and the delegation needsDelegate=cpu memory pids, which the refusal names. All three blank means no cgroup probing at all, except underresource-only(which always creates its cgroup) and when launching with tclaude’s sandbox on Linux (which tries, and degrades to a notice if the host cannot). macOS,off, and hosts without delegated controllers refuse by default every cgroup a launch cannot proceed without — an authored ceiling under any implementation, andresource-onlyeven with no ceiling; the dashboard's "Allow launch with unenforced rules" checkbox is the one operator escape hatch and records a visible degradation notice. Only the opportunistic layer boundary degrades instead.darwin_allow_mach_register— a Seatbelt(allow mach-register)opt-in for browser/XPC workloads on macOS.pre_launch— named, ordered operator-authored shell fragments that run inside the sandbox, after profile environment export and before the harness starts (≤ 32 blocks, ≤ 64 KiB of script). They hold no extra authority and take no part in lineage containment.includes— compose other profiles by name (≤ 32 references, include depth ≤ 16, acyclic). Included profiles apply first in listed order, then the including profile's own rows; for the same exact path or environment name the later layer wins, so a local grant can override an included deny. That is authoring convenience inside one registry — cross-scope composition below is deliberately not last-wins.
Protected roots¶
~/.tclaude/data and ~/.claude/sessions are an absolute wall. No profile,
include, launch contract, or flag reopens them, and any read/write rule at or
below one is refused. A rule on an ancestor is allowed and keeps the wall:
{"path": "~", "access": "write"} makes the whole Home writable, including
directories created later, while the protected roots stay hidden on top of it
under every implementation that enforces access rules (off and
resource-only enforce none, so there the row changes nothing).
tclaude’s sandbox also pins the directories between the grant and each
protected root (~/.tclaude, ~/.claude) so they cannot be renamed or
removed: on Linux they become mount points, on macOS they get an unlink deny.
Their contents stay writable. A harness-native sandbox has no way to express
that pin, so a write row on an ancestor is refused under harness-builtin
with unsupported_sandbox_profile_protected_ancestor_write; a read row is
fine. An ancestor row with a mount_path is refused everywhere, because the
projection would carry the protected tree to a sandbox path the re-hide does
not cover.
Comparison is by
filesystem identity, not string: case or Unicode-normalization spellings of a
protected root are refused alike, on every volume, including for paths that do
not exist yet. ~/.codex is not protected and must be reopened under a denied
Home, which makes a strict-Home profile materially easier to run under Codex
than under Claude Code.
macOS Keychain access¶
On macOS, tclaude’s sandbox automatically grants read/write access to
~/Library/Keychains for every harness, alongside the harness state directory.
This supports credential persistence through macOS Keychain APIs without a
per-profile filesystem grant. In the profile editor’s macOS compatibility
section, uncheck Allow macOS Keychain writes to opt out
(darwin_disable_keychain_write: true). An opt-out in any included or applied
profile wins. This removes the automatic grant; explicit filesystem grants
still apply. Disabling it may prevent harnesses from saving or refreshing
vendor/provider login credentials. The grant covers the shared user Keychain
directory, not just the selected harness’s credential item; macOS Keychain
access controls still apply. Harness-native sandbox policies are unchanged.
The harness-config floor¶
Under tclaude’s sandbox the launch contract binds the harness's state root
read-write — ~/.claude, $CODEX_HOME/~/.codex, $COPILOT_HOME/~/.copilot,
~/.gemini (or $GEMINI_CLI_HOME/.gemini), tclaude's walled pi agent
directory (~/.tclaude/pi-agent/…, with pi's session store),
~/.opencode plus OpenCode's XDG roots — because that is where the harness
keeps state it genuinely must write: transcripts, project records, todos,
history, account/onboarding data. The same tree also holds the harness's
policy and persistent-code surface, and writing that is an escape:
~/.claude/settings.jsoncarries the blocktclaude setup --install-sandbox-hardeninginstalls. Strip it and the wall around~/.tclaude/dataand~/.claude/sessionsis gone for everyharness-builtinlaunch and for the human's own ambientclaude.~/.codex/tclaude-agent.config.tomlis the managed profile that provides Codex'sharness-builtinconfinement.- A hook, skill, agent, or command dropped under
~/.claude/hooks(and friends) runs in the human's next, unsandboxed session. - An allow rule appended to
~/.codex/rules/default.rulespre-approves a command for every later Codex session, unsandboxed ones included.
So tclaude binds a closed per-harness catalog of those paths read-only by
default, creating missing directories first — an absent ~/.claude/hooks under a
writable state root is just a directory the agent can create. The floor is
enforced by the ordinary read-grant path, so it appears in
sandbox-profiles plan as launch-contract / harness-config-floor on both
bubblewrap and Seatbelt.
| harness | floored |
|---|---|
| claude | hooks/, skills/, agents/, commands/, output-styles/, plugins/, workflows/, routines/, rules/, local/, cowork_plugins/, settings.json, settings.local.json, CLAUDE.md, keybindings.json |
| codex | hooks/, prompts/, rules/, config.toml, hooks.json, AGENTS.md, tclaude-agent.config.toml |
| copilot | hooks/, settings.json, config.json, mcp-config.json |
| gemini | extensions/, commands/, skills/, agents/, policies/, settings.json, .env, trustedFolders.json, trusted_hooks.json, policy_integrity.json, GEMINI.md |
| pi | nothing — a walled pi runs against tclaude's walled copy of its agent directory (~/.tclaude/pi-agent), and the operator's agent directory is read-only as a whole apart from its session store; see pi |
| opencode | nothing — its config tree is already bound read-only by OpenCode's own state layout, in both legacy-shared and private modes |
Claude Code's own sandbox deny-writes a broadly similar set for its Bash tool; without the floor tclaude’s sandbox was weaker than the harness's own default.
Only directories are created. A file the host doesn't have is left out of the floor and never written, so an absent file stays writable: an agent can create it, and it takes effect in your next unsandboxed session. The table lists candidates, not a guarantee. To close the gap, create the file yourself, since a file that exists is bound read-only. Existing content is never touched.
Symlinked entries are skipped, with a warning naming the path. Dotfile
managers commonly point ~/.claude/skills at a repo, and there is no faithful
way to floor that: binding the resolved target leaves the name an ordinary
symlink inside the writable state root, which the agent can unlink and replace
with a real directory of its own. Skipping is disclosed; flooring the target
would be a false claim. Point the symlink the other way — make ~/.claude/hooks
the real directory — if you want it floored.
What it costs. Unlike Claude Code's Bash-only deny list, a bubblewrap
read-only bind blocks everyone inside the wall, the harness process included.
In-pane writes to a floored file therefore fail: Claude Code's /config and
user-scope /permissions, Codex's /model persistence and its "don't ask
again" command approvals (Codex warns that it could not save the rule and runs
the approved command once; the next one asks again), Copilot's trust-folder
record. /model and directory trust for Claude Code land in
.claude.json, which stays writable.
Three escape hatches, least blunt first:
- An explicit profile write row at exactly one floored path drops that
single entry —
{"path": "~/.claude/plugins", "access": "write"}reopens plugin installs and nothing else. A broader~or~/.claudewrite does not count: the operator has to name the surface. A row beneath a floored directory (~/.claude/hooks/mine) reopens only that path and leaves the floor over the rest of the directory intact. A floored file is reopened the same way —{"path": "~/.claude/settings.json", "access": "write"}— since a row may name a single file, though that row needs tclaude’s sandbox on Linux and is refused underharness-builtinlike any other file row. "harness_config": "write"turns the whole floor off, restoring the pre-floor posture — but only when nothing else in the chain pins it. Composition is strictest-wins, so an explicit"read"in any included, global, group, or explicit profile outranks a"write"anywhere else. That asymmetry is deliberate: it lets an operator pin the floor globally and know a per-spawn profile cannot quietly undo it.--harness-config read|writeat spawn time, for granting one agent the posture without authoring a profile for it:
Unlike the profile chain this is a launch contract, not a fourth scope: it
overrides the composed value outright, the same way --omit-sandbox-profiles
overrides the ambient tiers rather than merging with them. A human may set
it directly; an agent needs the sandbox.harness-config permission,
which is not default-granted and which group ownership deliberately does not
confer — lifting the floor lets the launched agent rewrite the policy that
confines it. write cannot be combined with --omit-sandbox-profiles,
whose snapshot records "no profile tier applied at all"; read is accepted
there as the no-op it is, since the floor is already what an absent value
means.
The slug gates selection, never enforcement. The floor is a mount frozen
at launch, so no permission makes a running agent's config surface writable,
and lineage still refuses a child posture
wider than its recorded parent's — an agent holding the slug can pin the
floor on a child, but can only pass write down if it already has it.
Agents relaunched before #3817 may have lost it. Resume, reincarnate
and some clones used to rebuild the policy from the profile chain without
the explicit posture, so a read pin over a write chain widened to
write. To find them:
This lists every active agent whose recorded launch no longer carries the posture its spawn request asked for, marked as follows:
- widened: asked for the floor, now runs without it.
- narrowed: asked for
write, now runs under the floor. - unpinned: same posture today, but a profile edit could change it.
Retired agents are skipped, so the check stays quick on an install with a
long retired history. --include-retired lists them too, marked
retired. They are listed only: a retired agent is never restored.
The command only reads. To restore agents, use Diagnostics › Doctor in the
dashboard. It previews them with every agent selected, and you can deselect
any you want to leave as they are. Restoring writes the posture back into
each agent's recorded launch, and the next resume keeps it. A running agent
takes the posture when it next resumes, or when you restart it from the
preview. Both the list and the restore require sandbox-profiles.manage.
Some agents can't be found this way, because the finder needs the recorded spawn request:
- agents created by the pending-spawn sweeper or a group template, and promoted or backfilled agents, which have none;
- a clone whose own spawn request didn't name the posture.
The floor applies with tclaude’s sandbox.
Under harness-builtin the harness's own policy governs and the axis is
inert; under resource-only/off nothing is enforced by design. Lineage
treats it like any other containment rule: a floored parent cannot spawn an
unfloored child.
Reference: scoping playwright-cli to one agent¶
The worked example, and the reason pre_launch exists. It gives Playwright
private XDG directories, a per-agent session, and a fixed browser, without any
of that leaking into the agent's other tools. Pair it with
"agent_directories": ["TCLAUDE_PW_HOME"] so the directory is per-agent and
writable.
pw="$TCLAUDE_PW_HOME"
# Resolve the real binary with our own wrapper directory removed from PATH.
# Blocks re-run on every launch including resume, so by the second launch the
# wrapper may already be first on PATH; a plain lookup would find the wrapper
# and wrap it in itself, an exec loop that hangs with no output. Excluding the
# directory makes a re-run idempotent instead of fatal.
pw_search=""
IFS=: read -ra pw_parts <<< "$PATH"
for pw_entry in "${pw_parts[@]}"; do
[ "$pw_entry" = "$pw/bin" ] && continue
pw_search="${pw_search:+$pw_search:}$pw_entry"
done
real="$(PATH="$pw_search" command -v playwright-cli || true)"
if [ -z "$real" ]; then
echo "playwright-cli is not installed on this host" >&2
false # abort the launch; tclaude names this block in the failure
fi
export TCLAUDE_PW_REAL="$real"
mkdir -p "$pw"/{config,cache,data,bin}
# A QUOTED heredoc: nothing is interpolated at write time, so a directory
# containing $, backtick, backslash or quote cannot corrupt the wrapper. The
# wrapper reads both values from its environment at run time instead.
cat > "$pw/bin/playwright-cli" <<'WRAPPER'
#!/bin/bash
XDG_CONFIG_HOME="$TCLAUDE_PW_HOME/config" \
XDG_CACHE_HOME="$TCLAUDE_PW_HOME/cache" \
XDG_DATA_HOME="$TCLAUDE_PW_HOME/data" \
exec "$TCLAUDE_PW_REAL" "$@"
WRAPPER
chmod +x "$pw/bin/playwright-cli"
export PATH="$pw/bin:$PATH"
export PLAYWRIGHT_CLI_WRAPPER_DIR="$pw/bin"
# Playwright's downloaded browser bundles live under $XDG_CACHE_HOME, which we
# just made per-agent — so without this every agent would see an empty browser
# registry and re-download hundreds of MB. Keep the registry shared.
export PLAYWRIGHT_BROWSERS_PATH="${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}"
export PLAYWRIGHT_CLI_SESSION="$(basename "$pw")"
export PLAYWRIGHT_MCP_BROWSER=chrome
export PLAYWRIGHT_MCP_SANDBOX=false
Declare "exports": ["PLAYWRIGHT_CLI_WRAPPER_DIR", "PLAYWRIGHT_CLI_SESSION",
"PLAYWRIGHT_MCP_BROWSER", "PLAYWRIGHT_MCP_SANDBOX"]. Note what is not
there: PATH is always set, so declaring it would prove nothing — the check
is set-ness. The wrapper-directory sentinel is set alongside it and is
genuinely absent if the block did not get that far.
Five things are load-bearing:
- The wrapper, not a global export. XDG is exported inside the wrapper,
so only Playwright sees it. Exporting it into the agent would take
gh,git,codexandclaudewith it. - Resolve the real binary with the wrapper directory excluded from
PATH. Blocks re-run on every launch including resume; a plain lookup on the second launch would find the wrapper and wrap it in itself — an exec loop that hangs with no output. Excluding the directory makes a re-run a no-op. - A quoted heredoc. Nothing is interpolated when the wrapper is written,
so a directory containing
$, a backtick, a backslash or a quote cannot corrupt it; the wrapper reads both values from its environment at run time. PLAYWRIGHT_BROWSERS_PATHstays shared. The block just made$XDG_CACHE_HOMEper-agent; without re-sharing the browser registry every agent would re-download hundreds of megabytes of browser bundles.false, notexit 1. Letting the command fail trips tclaude'sERRtrap, which names the block in the failure message; an explicitexitbypasses it and the operator gets an unattributed exit code.
One limitation worth knowing: playwright-cli refuses the file: protocol
unless allowUnrestrictedFileAccess is set, and every way of setting it
grants the browser unrestricted filesystem reads (the global config also
lives in the agent's real $HOME, which this wrapper deliberately does not
redirect). Serve local pages over loopback instead.
This block is not prose nobody runs:
pkg/claude/session/pre_launch_playwright_reference_test.go executes it on
every test run and compares the fenced script above against the one it
executes, so the two cannot drift.
Strictness is a shape, not a mode¶
There is no "strict mode" switch. Strictness is composed from ordinary rows:
[
{ "path": "~", "access": "deny" },
{ "path": "~/git/myproject", "access": "write" },
{ "path": "~/go", "access": "read" }
]
A read/write grant strictly beneath a deny — a reopen-under-deny — is
detected as a shape, and that shape is capability-gated at launch: a backend
that does not honor most-specific-wins would run this strict-looking profile
with a broad baseline, so tclaude refuses the launch
(unsupported_sandbox_profile_reopen_under_deny) instead. The combinations
that can faithfully enforce it:
| Backend | Reopen-under-deny |
|---|---|
Claude Code, sandbox on |
supported |
Claude Code, sandbox inherit / off |
refused — the deny and the reopen may both be dropped |
Codex, managed tclaude-agent profile on Linux, split-policy probe verified |
supported |
| Codex on macOS | refused — the deny mask dominates narrower reopens (openai/codex#21081) |
Codex legacy Landlock, or a raw --sandbox mode |
refused |
Any other harness under harness-builtin |
refused |
tclaude’s sandbox enforces the
shape itself on both platforms. The gate keys on the rules tclaude will emit, not just the
rows you authored: a bare deny ~ with no reopens of your own still becomes a
split policy, because the launch contract adds its own reopens.
What tclaude reopens for you¶
Under a broad deny, tclaude pairs read reopens automatically for a short,
closed list: the workspace and daemon-verified git admin paths, the profile's
own write grants, declared agent_directories, the agentd socket, and — on
Codex only, when a probe proves it needed — the Codex executable. Everything
else is yours to enumerate. In particular, tclaude's own binary is not
implicitly reopened: under deny ~ an agent can reach the agentd socket and
still get tclaude: command not found until you reopen the directory holding
the binary (commonly ~/go/bin or a version-manager install root).
Gotchas worth knowing before you debug: on Linux, a write under a deny can fail
silently (exit 0, file gone by the next command — the write landed in a
throwaway mount layer), and ls ~ shows only reopened paths; on macOS,
Seatbelt returns ordinary permission errors and denied names stay enumerable.
command not found for a tool plainly on $PATH usually means its install
root is denied — and reopening toolchain caches is not enough to build if the
compiler binary itself sits under the deny. Claude Code's built-in denies mask
some paths with /dev/null device nodes on Linux, which makes git add -A
fail ("can only add regular files"); stage specific paths instead.
Attachment: global, group, explicit¶
Profiles attach at three tiers: a global default, a group assignment,
and an explicit per-spawn profile (--sandbox-profile on
tclaude session new — human-only — plus spawn profiles, the dashboard, and
tclaude agent spawn). --omit-sandbox-profiles (human-only) omits all three
tiers, and the omission is recorded in the launch snapshot so a resume or
reincarnation cannot resurrect the ambient tiers.
A launch mode that cannot carry tclaude sandbox profiles (Codex's
danger-full-access, for example) omits them too, but that omission is the
mode's, not the agent's choice. While the agent keeps that mode, its relaunches
keep omitting the profiles. Once its mode can carry them again, the next resume
or reincarnation applies the global and group assignments as they are then,
plus the profile its spawn named with --sandbox-profile when its launch
recorded one and that profile exists.
Scribe and Steward summons, and trigger and process workers, get the global
and group tiers like any other spawn into their group, along with the group's
environment. A scribe or Steward with no profile and no environment configured
launches with no sandbox snapshot, as it always has. A scribe's sandbox is the
operator's policy for its group, so it is not checked against the sandbox of
the agent that summoned it. A scribe always works in ~/.tclaude/scribe, and a
Steward there too unless steward.dir names another directory, so a profile
that denies exactly that directory refuses the summon with an error naming the
profile. A deny on an ancestor, such as the home directory, does
not: the launch reopens its workspace, as it does for every agent.
Cross-scope composition is not last-wins:
- Filesystem: a canonical-path union where deny dominates write dominates read, regardless of tier — an explicit profile cannot un-deny a global deny. A strictly narrower later row survives as a reopen-under-deny and then meets the capability gate above.
- Environment: last scope wins (global → group → explicit).
- Network: allow authority intersects across scopes while deny authority
unions;
closeddominates. Unix-socket lists intersect. network.namespace: privateandfilesystem_root: separatecompose monotonically — a later scope cannot widen them back to host/inherit.network.engineis the one precedence field: most explicit wins (explicit > group > global), with a disclosure when composition was overridden.
The sandbox-profiles CLI¶
tclaude agent sandbox-profiles ls
tclaude agent sandbox-profiles show <name>
tclaude agent sandbox-profiles create --file profile.json
tclaude agent sandbox-profiles edit <name> --file profile.json
tclaude agent sandbox-profiles rm <name>
tclaude agent sandbox-profiles default show|set|clear
tclaude agent sandbox-profiles group show|set|clear <group>
tclaude agent sandbox-profiles export [name…]
tclaude agent sandbox-profiles import --file bundle.json
tclaude agent sandbox-profiles plan --group <g> --sandbox-profile <name>
tclaude agent sandbox-profiles plan --agent <selector>
Exporting an agent's debug configuration¶
When a sandbox behaves differently from the operator's shell, export the configuration recorded for that specific agent instead of trying to recreate its launch from current defaults:
An agent can omit <agent> to export its own configuration. Exporting another
agent requires agent.debug-export, the group-scoped
groups.members.debug-export, or ownership covering the target's active
groups. The Groups dashboard exposes the same download as export debug info
in each agent's cog menu, including for offline agents.
The versioned JSON deliberately separates three configurations:
requested— the original spawn parameters, including which values were omitted;resolved— durable resume/relaunch values and the exact composed sandbox snapshot, including applied-profile provenance, filesystem grants, environment values, harness-config posture, network/socket rules, resource limits, and pre-launch blocks;running— the latest recorded launch's harness mode, sandbox implementation, model/effort, status/error detail, OS-sandbox verdict, approval posture, effective policy, and a versioned execution-boundary record. The boundary includes the resolved harness executable/runtime roots, the hosttclaudesource and its sandbox mount target, automatic static-root and daemon-final mounts, the materialized outer-layer render input, PATH construction and pre-launch mutation caveats, and host-to-sandbox UID/GID mapping.
The export records agentd's current UID/GID/groups separately from the launch
boundary's host and sandbox identities. On Linux it also reads the recorded
live harness process through /proc and reports its host-visible real,
effective, saved, and filesystem UID/GID values, supplementary groups, and
the kernel's live uid_map/gid_map, actual executable path, and current
PATH. A stopped process, an unreadable /proc entry, or a
platform without that observation is reported explicitly as unavailable or
unsupported; the export never substitutes agentd's environment for the
agent's.
The export also records the tclaude version and host platform. Environment values and local paths are intentionally included because they are often the cause of sandbox failures, so treat the file as sensitive. Initial task text and one-time authorization tokens are redacted.
Renames go through edit (change the JSON name; stable-ID assignments
follow). import is transactional, with assignment application opt-in.
draft --token --file is the scribe seam: a dashboard-summoned drafting agent
holding only sandbox-profiles.draft can propose a validated profile for human
preview but can never save, assign, or launch. In the dashboard, configure
with agent asks you to confirm that grant, then opens the scribe in its
regular overlay chat window; the draft it returns opens in the editor for
review. Payload reads (show) and all
writes require sandbox-profiles.manage — human-only by default, and
deliberately not implied by profiles.manage; reading the global and group
assignments does not.
plan is inspection-only, in two modes. Hypothetical mode composes the current
global, group, and explicit tiers for a directory (--cwd,
--for impl[/harness[/platform]]), predicts access enforcement, and describes
the four outer-layer mount precedence classes. --agent mode reads only the
latest frozen launch row — it never re-resolves registry profiles or stats
paths, and marks classes the row did not record as unavailable. Both support
--json; missing positive binds report missing-would-skip.
The dashboard carries a full profile editor with a common-rules catalog — a
portable deny tier for SSH keys, GnuPG, cloud and container credentials, VCS
tokens, toolchain caches (with a build-breakage warning), browser profiles, and
a "Deny access to the Home directory" rule that inserts an ordinary editable
deny ~ row.
Lineage and spawn write-proofs¶
Confinement is heritable, in one direction only. Resume, reincarnation, and
agent-initiated child spawns can never weaken a deny or introduce a reopen the
parent lacks; both count as widening and are refused. The check is
specificity-aware — a broad parent read above a deny does not "cover" a child's
reopen beneath it. A resume or reincarnation re-reads the agent's sandbox
profiles and revalidates the result. If the re-read profiles cannot be
applied (an explicit profile was deleted, the agent's groups now assign
different profiles, or the rules no longer validate or cannot be enforced for
this launch), it relaunches under the policy stored at the agent's last launch
and returns a warning saying why. It refuses only when the stored policy
cannot be launched either (on resume, as sandbox_profile_changed). Humans are the trust
root and bypass lineage.
An agent's child gets its sandbox as follows:
- Into the parent's own group, naming no profile: the child inherits the
parent's selected profiles, resolved the way the parent's own next relaunch
would resolve them. Under the relaunch policy's
sandbox_profile_contentsrow, re-resolve (the default) gives their current contents and reuse gives the contents stored at the parent's last launch. An operator who edits the parent's profiles while it runs, widening or narrowing them, edits its children too. That edit is the operator's, not an escalation by the parent. - Into another group, naming no profile: the child takes that group's
assignment. It must fit inside the parent's configuration as resolved now,
and a group that assigns more than the parent has is refused
(
sandbox_profile_restricted). - Naming a profile explicitly: the child gets that profile, which must fit inside the parent's configuration as resolved now, the same bound.
Members of a template the parent instantiates, and agents launched on its behalf, are held to that bound too. If the parent's profiles cannot be used now, as when one was deleted, the bound is the policy stored at its last launch, as the parent's own relaunch would fall back to. Judging the bound creates nothing on disk: the parent's agent-owned directories are not probed or recreated for it.
In every case the child's own --harness-config posture is applied last and
checked with the profiles. A parent's own explicit posture is not inherited.
Spawns by a peer, a federation request or an external steward have no parent
sandbox here: they take the target group's assignment.
Denying a child more: --sandbox-deny¶
A spawner can deny its child paths on top of whatever profiles the child resolves:
The API field is sandbox_deny: absolute paths, or ~/… under the daemon's
home. The CLI expands ~ and makes relative paths absolute. In the
dashboard's spawn dialog, Deny paths (under Sandbox profile) takes the
same paths as chips. It flags a relative path and a deny over the working
directory, and when the chosen sandbox cannot enforce a deny it says so and
keeps the paths, so the spawn is refused rather than launched without them.
It is not offered for a spawn on another node.
- A denied path covers its whole subtree. A more specific grant beneath it, which profile composition alone would keep (the most specific rule wins), is removed. The same goes for a temporary filesystem or a Unix socket allowed there, and for a grant that mounts an ancestor of the denied path at another sandbox path, since that path would expose the subtree. A composition notice on the launch names what was removed.
- It is the agent's configuration. The overlay is stored with the child and reapplied at every resume and reincarnation, under re-resolve and reuse alike. A later profile edit that adds a grant beneath a denied path is removed again at the next relaunch rather than reopening it.
- It is inherited. A child's overlay is its parent's plus its own, into the parent's group or another, so denies only accumulate down a lineage. A child can never drop its parent's. Members of a template the agent instantiates, and agents launched on its behalf, inherit it too.
- It fails closed. A spawn or relaunch whose launch would not enforce
the overlay is refused: a sandbox implementation of
offorresource-only, or a mode that omits the sandbox profiles (--omit-sandbox-profilesis refused alongside--sandbox-deny), and an operator's temporary sandbox-off restart. - A launch never reopens it. A launch opens some paths for itself: the working directory, the workspace's Git administrative directories, the harness's own state, and agent-owned directories. A denied path covering one of those is not opened for it; the launch is refused and the error names the path. The spawn request is refused up front for the working directory and the Git directories; the rest are only known when the session assembles its launch, and a spawn, resume, reincarnation or clone fails there instead.
The overlay denies filesystem paths only. External steward spawns cannot set it, and a group exported and imported elsewhere lands without it.
A second guardrail closes the anchor-point escape: a sandboxed parent choosing
a child cwd its own sandbox cannot write. agentd answers such a spawn with a
single-use challenge (write_proof_required); the parent must create the
dot-prefixed proof file in each target directory from inside its own sandbox
and retry, and agentd verifies and deletes the proof. Humans, fully open
parents, and children that take no cwd write are exempt. The full guardrail
list lives in Spawning and lifecycle.
Hardening tclaude's own state¶
tclaude setup --install-sandbox-hardening protects the daemon's trust anchors
— ~/.tclaude/data (database, config, operator token, remote-access CA keys)
and ~/.claude/sessions (identity forgery) — from the agents it coordinates.
agentd's identity and permission layer is a coordination guardrail, not a
security boundary; the OS sandbox is what makes it hold.
The installer writes an append-only, idempotent block into user-scope
~/.claude/settings.json covering both Claude Code layers, because neither
alone is enough:
- Layer 1, the OS sandbox (
sandbox.enabled: true,failIfUnavailable: true,allowUnsandboxedCommands: false, filesystem deny-read/deny-write on both protected trees with the agentd socket re-allowed, andallowedDomains: github.com, api.github.com). A kernel boundary — but it applies only to Bash commands and their children, not to the built-inRead/Write/Edittools. That gap is verified: theWritetool created a file under~/.tclaude/on a machine whose Bash sandbox treated it as read-only. - Layer 2, permission rules (
permissions.denyRead(…)/Edit(…)mirrors). These gate the built-in tools — and are string matching, not a boundary, so an arbitrary subprocess that opens a file itself slips past them. Layer 1 contains what layer 2 cannot see; layer 2 gates what layer 1 does not reach.
The installed block, in full — user scope, ~/.claude/settings.json, so no
project can weaken it (tclaude setup --install-sandbox-hardening merges it
append-only and idempotently; a test keeps this block and the installer's
in-code spec identical):
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false,
"network": {
"allowUnixSockets": ["~/.tclaude/api/agentd-socket/agentd.sock", "~/.tclaude/api/agentd.sock", "~/.tclaude-agentd.sock", "~/.tclaude/agentd.sock"],
"allowAllUnixSockets": true,
"allowedDomains": ["github.com", "api.github.com"]
},
"filesystem": {
"denyWrite": ["~/.tclaude/data", "~/.claude/sessions"],
"denyRead": ["~/.tclaude/data", "~/.claude/sessions"],
"allowRead": ["~/.tclaude/api/agentd-socket", "~/.tclaude/api/agentd.sock", "~/.tclaude-agentd.sock", "~/.tclaude/agentd.sock"]
}
},
"permissions": {
"deny": [
"Edit(~/.tclaude/data/**)",
"Read(~/.tclaude/data/**)",
"Edit(~/.claude/sessions/**)",
"Read(~/.claude/sessions/**)"
]
}
}
Re-run the installer after upgrades — older installs lack newer keys such as
failIfUnavailable. Conflicting scalars are preserved and reported. On shared
machines, use managed settings with forbidUnsandboxedCommands: true. tclaude
also applies a per-launch overlay denying the exact tmux socket path on Linux, so
agents cannot send-keys at tclaude's tmux server. macOS's built-in sandbox has no
exact socket deny, and the overlay is skipped in mode off.
Honestly residual holes¶
- Settings files you don't have aren't floored. An agent can create an absent
settings.json,CLAUDE.md,AGENTS.mdor similar file in the harness config directory, and your next unsandboxed session reads it. See the harness-config floor. ~/.claude/.claude.jsonstays writable, and it carriesmcpServers. Under tclaude’s sandbox the harness-config floor cannot cover it: Claude Code writes that file continuously (project records, directory trust, history), andCLAUDE_CONFIG_DIRputs it inside the same writable state root. An agent that appends anmcpServersentry there gets that command executed by the next tclaude-launched Claude pane — including aharness-builtinone with no outer wall. This is the residual member of the same escalation family the floor closes, and closing it needs a different mechanism than a read-only bind.- Gemini's floor protects only the policy files that already exist. Like
every floor entry, a missing file is not materialized, and in a typical
~/.geminimost of the dangerous ones are missing:.env,trusted_hooks.json,policy_integrity.json,GEMINI.md, andtrustedFolders.jsonuntil--trust-dirfirst writes it. A walled Gemini agent can create~/.gemini/.env(loaded into the environment of the operator's nextgeminiin a trusted folder: base URLs,GEMINI_SYSTEM_MD,NODE_OPTIONS) or atrustedFolders.jsonthat trusts/. An empty placeholder is no fix for.env: Gemini stops at the first.envit finds, so an empty~/.gemini/.envwould hide the operator's~/.env. To close the hole, create the files you care about yourself; once present, they are bound read-only. - Codex's project layer lives in the workspace. In a project Codex
trusts, it also loads
<repo>/.codex/config.tomland<repo>/.codex/rules/*.rules. Both sit in the writable workspace, outside the floor's state-root catalog, so an agent can still add allow rules that your next unsandboxed Codex in that repo honors. Review.codex/changes the way you review code. - MCP bypasses both layers entirely. MCP servers run in the harness host
process over their own transport, outside the Bash sandbox and the permission
rules. An agent that cannot see
~/.config/ghmay still file a GitHub issue through an MCP server. Control MCP where MCP servers are configured, not in the profile. - Linux Unix-socket widening. Claude Code's Linux seccomp filter cannot see
socket paths, so the only knob is
allowAllUnixSockets: true— a deliberate widening the installer accepts to keep the agentd socket reachable (the path-list form works on macOS only). - Reopen-under-deny is layer-1-only. Leaf denies are mirrored to layer 2,
but a deny with a reopen beneath it cannot be expressed as Claude Code
permission rules (deny rules carry no exceptions), so under a
deny ~profile the built-inReadtool can still read denied paths unless you add user-scope leaf rules yourself. tclaude logs a warning naming each deny it could not mirror. - The GitHub domain allowlist is itself an exfiltration path; full sandbox escape is out of scope (the trust boundary is the Unix UID); and the sandbox badge is a launch-time verdict — resume re-resolves it.
The dashboard badges the posture per agent: 🔒 sandbox on,
⚠ off, unknown or not fully enforced, nothing for plain inherit. An unsandboxed-autonomy warning
fires wherever auto-approval pairs with an unprovable sandbox. The
credential proxies are what make denying ~/.ssh and
~/.config/gh survivable for agents that still need to push branches.
Deep dives¶
Namespaces every Linux posture takes¶
Network and PID namespaces are posture-dependent — they cost real capability (no host IP, no host process table) and are paid only where a posture's claims need them. Two others are requested in every posture, including the walking-skeleton host-open one that keeps the host network namespace and the read-only host root. Only one of the two is guaranteed, and the difference matters:
- IPC. This closes System V IPC and POSIX message queues. Neither is a
filesystem object:
shmget/semget/msggettake integer keys, andmq_openresolves its name against the IPC namespace's own internal mount rather than any path —/dev/mqueueonly makes queues browsable, it is not what makes them work. Both are permission-checked by uid, so a sandboxed process running as the invoking user would otherwise reach every segment, semaphore, and message queue that user owns on the host, in either direction, with nothing a mount plan could do about it. This is the one flag here that an enforcement claim rests on, so it is a hard requirement: a kernel that cannot build an IPC namespace refuses the launch. - cgroup, via
--unshare-cgroup-try. An information boundary, not a containment one, and a partial one — nothing claims otherwise. Escaping a cgroup needs a writable/sys/fs/cgroup, which no posture provides, so there is nothing here to contain. What it closes is/proc/self/cgroupnaming agentd's delegated node and the session inside it, and it closes that fully only under a constructed root, which binds no/sysat all. Under the walking skeleton's recursive read-only host root,/sys/fs/cgroupis still mounted from the parent namespace — a cgroup namespace re-roots/proc/PID/cgroupand freshly mounted cgroup2 filesystems, not an inherited mount — and that posture has no PID namespace either, so the layout is still recoverable by finding your own host PID undercgroup.procs. The-tryspelling follows from that: cgroup namespaces need kernel 4.6, and refusing a launch over a partial disclosure fix that backs no enforcement claim would be the wrong trade. So this one is best-effort, not guaranteed: on a kernel or under an outer confinement that refuses the namespace, the launch continues without it and/proc/self/cgroupreads the host path as before. Nothing else about the posture changes, because nothing else depends on it — but do not treat cgroup hiding as a property you can rely on. Your workload's resource ceiling is unaffected either way —resource-limit-execruns outside bubblewrap and puts the workload in the cgroup before the launch command execs.
Two consequences worth knowing:
- System V IPC and POSIX message queues are now absent in every posture,
including the default one.
ipcsshows nothing, and anything relying on shared-memory IPC with a host process — X11 MIT-SHM against a host X server is the classic case — degrades or fails. This is whydocker run --ipc=hostexists. Harmless for terminal-driven harnesses, which is what this layer wraps. - A nested
tclauderun inside a sandbox sees0::/and cannot derive a delegated cgroup parent from it — when the cgroup namespace was created at all; see the best-effort note above. With noresource_limitsauthored that degrades with a diagnosis. With a ceiling authored it fails closed, exactly as an undelegated host does — there is no flag to wave it through; the dashboard's "Allow launch with unenforced rules" fresh-spawn control is the only thing that widens it.
UTS is deliberately not unshared. The sandbox already cannot change a hostname
— that needs CAP_SYS_ADMIN in the user namespace owning the host's UTS
namespace, which is the initial one, and bubblewrap drops all capabilities. A
synthetic hostname would be a concealment feature rather than a boundary, and
it would need a synthesized /etc/hosts in every posture to avoid breaking
getaddrinfo(gethostname()), since /etc is bound whole from the host.
Isolated-with-agentd network posture¶
The profile's network_access field maps differently because the outer layer
wraps the whole harness process, not only its tool executions:
- omitted (
inherit) andinternetuse the host-open posture. This preserves the walking skeleton: the host network namespace and read-only host root remain visible, including host localhost services and ambient filesystem Unix sockets.internettherefore means more here than a tool-only Internet switch; the launch record calls thishost networkrather than repeating the profile word. nonerequests isolated-with-agentd. Bubblewrap creates a fresh network namespace (with loopback up), a fresh PID namespace, and a constructed filesystem root. Bubblewrap remains PID 1 so orphaned harness subprocesses are reaped. There is no blanket bind of/: the static OS surface is read-only (/usr,/bin,/sbin,/lib*,/etc, and/opt, accounting for merged-usr symlinks);/devand/procare fresh,/tmpis tmpfs, and/run,/var,/srv,/media,/mnt,/boot, and/rootare absent. Home paths exist only where the launch contract or ordered profile plan binds them. The canonical~/.tclaude/api/agentd-socket/directory is bound read-only as a launch-contract path, so socket replacement remains visible across agentd restarts.
Since TCL-798 the constructed root is no longer welded to the network posture.
A sandbox profile can select the filesystem root explicitly with
filesystem_root: omit it for Automatic, use inherit to prefer the
read-only host root, or use separate to request the minimal constructed root
even when network and Unix sockets remain open. Explicit separation is
supported by tclaude’s sandbox on Linux for Claude Code, Codex, OpenCode,
Copilot, Gemini CLI and shell; pi and other targets refuse it during preview/spawn rather than ignoring it.
The setting composes monotonically. separate in any included, global, group,
or explicit profile wins. inherit cannot weaken a private/restricted network
or Unix-socket rule whose enforcement itself requires a constructed root. This
keeps existing profiles unchanged: an omitted setting retains the same
automatic derivation they had before the control existed.
A profile that leaves network access open but authors the unix_sockets axis
as closed or an allow list gets a host-network constructed root on
Linux for Claude Code, Codex, OpenCode, Copilot, Gemini CLI and shell, but not pi:
bubblewrap builds the same fresh
root and PID namespace as the isolated posture, binds the agentd socket and any
listed sockets back, and does NOT create a network namespace, so host IP
networking, host loopback services, and the IDE bridge keep working. For
OpenCode, the attach pane remains outside while its agentd-owned tool server is
wrapped by that root. Gemini CLI finds its IDE companion through files under
/tmp, which the constructed root replaces with a fresh one, so Gemini's IDE
integration may not connect in this posture.
A constructed root carries only the OS surface and your grants, so a harness
installed under your home directory would be missing from it. tclaude resolves
the harness executable on the host before entering the root and mounts it
read-only: Claude Code's versioned binary, Codex's native runtime, and for
Gemini CLI the npm package, any of its dependencies installed beside it, and
the Node interpreter its #!/usr/bin/env node line would find (an npm user
prefix, nvm, mise, …). Gemini is then started as <node> <bundle> by absolute
path, so the shebang's PATH lookup never runs inside the root.
That posture is deliberately rated partially enforced, permanently. With the
host network namespace shared, Linux abstract-namespace Unix sockets (@…) are
not filesystem objects at all, so no mount plan can hide them; close network
access as well if you need those confined too. The sibling non-filesystem
channels — System V IPC and POSIX message queues — are closed here, since
every posture unshares the IPC namespace, so abstract sockets are the
remainder rather than one example of a class. The recursive-root remainder
applies here as it does under closed network access: a socket beneath a
directory the profile makes readable or writable stays reachable.
The PID namespace is a requirement of this posture rather than a side
effect, and it has a cost worth knowing before you author the axis. Without it a
host process's /proc/<pid>/root leads straight back to the sockets the
constructed root just hid, so the posture's whole claim would be false. The
consequence is that the agent cannot see or signal host processes, and tools
that read the host process table stop working. This is stated in the launch
warning alongside the abstract-socket caveat.
It is never newly enabled by an omitted setting. A profile that says nothing
about filesystem_root, says nothing about unix_sockets (or sets sockets to
open), and has no network rule requiring construction launches with exactly
the read-only host root it launched with before.
Two consequences of building the root reach beyond sockets, and both are stated in the launch warning rather than left to be discovered:
- What the agent can see narrows. Host paths outside your filesystem grants
and the static OS surface are no longer present at all, where a host-open
launch without this rule showed the whole read-only host root. Before adding a
socket rule to an existing host-open profile, check that anything the agent
needs — toolchains under your home,
/var,/srv,/opt-style installs — is actually granted. - Sockets on the static OS surface stay reachable.
/usr,/bin,/sbin,/lib*,/etc, and/optare mounted read-only, and a read-only mount does not blockconnect(), so an AF_UNIX socket living under one of those paths remains connectable. This is the same remainder the closed-network posture has, named here because a host-open profile is a far more common shape.
The isolated posture has an explicit platform delta:
| Property | Linux (bubblewrap) |
macOS (Seatbelt) |
|---|---|---|
| Public and host-loopback connectivity | Unavailable outside the private network namespace | Refused by Seatbelt network operations |
| Harness-internal localhost server | Works on the private namespace's own loopback | Refused: Darwin loopback is host loopback, so reopening it would also reopen the IDE-bridge/host-service surface |
| Agentd | Canonical socket bind-mounted into the constructed root | Canonical socket and surviving aliases are the only outbound Unix-socket exceptions |
| Processes and filesystem root | Isolated PIDs and a constructed root | No PID isolation and no constructed root; hidden paths remain enumerable |
tclaude writes the macOS profile in a fixed rule order: (allow default)
first, then every deny, and every other allow (darwin_allow_mach_register,
Local access ports) last. Seatbelt is usually described as last-match-wins,
where the order of unrelated rules would not matter. It does not behave that
way: a later deny on a Unix-socket path intermittently overrides an earlier
TCP localhost allow, even though that deny cannot match the TCP connect.
Measured on macOS 26.7.2 and 27.2, the earlier allow lost about 1 connect in
10 and 8 in 10. With every allow last, it won every time. The isolated posture
has no separate allows. Its exceptions sit inside the deny itself
(require-not), and that form holds. The macOS assumption suite checks both
orders on every macOS CI run.
The stricter Darwin localhost behavior is deliberate. If a real harness later requires an internal localhost server, the remedy is a harness-descriptor capability plus launch-time refusal for Darwin isolated mode. It must not gain a loopback exception that silently reopens host services.
If a fresh dashboard spawn requests closed network access on an implementation that cannot enforce it, the launch normally refuses with:
<harness> (<scope> scope) cannot enforce closed network access; choose a sandbox implementation that can enforce closed network access, use network open, or enable “Allow launch with unenforced rules” in the dashboard spawn dialog
The human operator may explicitly check that named dashboard escape hatch for
one fresh launch. This also drops network deny rows the target can't enforce and
waives resource limits the host can't apply, each with a recorded notice. It admits
pi auto outside the wall too, which shows up only in the spawn audit. For a
closed-network gap, network
access becomes open, while enforceable filesystem and Unix-socket rules
keep their planned posture. Protected-root checks, filtered model-transport
gates, implementation availability, and other launch refusals remain
non-overridable. Raw API callers, including agents and human-class credentials,
cannot set the override; an authorized federated spawn can.
The network authorization is deliberately neither saved nor inherited. Resume,
reincarnate, and clone of an overridden agent do not carry it forward and refuse
again unless a future fresh spawn is explicitly authorized in the dashboard. Two
things differ: a pi auto agent's resume, reincarnation or no-copy clone keeps its
posture, and a waived resource limit's notice stays on the launch record.
The launch snapshot records a degradation notice with network reason
operator_unenforced_launch_override and effect not_enforced; the dashboard
renders a warning badge and the exact notice rather than claiming a sandbox
lock or changing the recorded OS-sandbox verdict. The same goes for any other
degradation notice with that effect, such as operator_reduced_network_deny_override
for omitted deny entries; only a resource_limits notice leaves the lock.
A sandbox that is on but enforces a rule more loosely than configured, recorded
as a notice with effect enforced_wider, gets the same warning badge. Its hover
says PARTLY ENFORCED, confirms the sandbox is on and names what is loose. This
is display only: the launch and its enforcement are unchanged, and the badge
keeps the click that temporarily disables the sandbox.
An untrusted bwrap¶
Symptom. Every launch with tclaude’s sandbox refuses with tclaude’s sandbox could not
resolve a trusted bubblewrap (bwrap), naming a path component and one of
group/world writable, not a regular executable, or is not a directory.
bwrap itself runs fine from a shell.
Cause. tclaude resolves bwrap from PATH, follows it to its real path,
and walks that path and every parent directory up to /. A launch is only as
trustworthy as the binary that builds its sandbox, so a bwrap anyone can
replace is refused rather than exec'd. The same walk applies to the
filtered-network helpers (pasta, nft, nsenter) — see
network filtering.
The walk requires that no component is group- or world-writable, that the
target is a regular file with an execute bit, and that every parent is a
directory. Ownership is not checked, so a bwrap you built and installed
under your own prefix is fine; a world-writable directory anywhere above it is
not.
Fix. Tighten the offending component (chmod go-w), or install bwrap
somewhere that already satisfies the walk. The refusal names the exact
component, so there is no guessing.
Not the cause. This is unrelated to unprivileged user namespaces: the walk runs before the capability probe, so a trust refusal means the probe never ran. A namespace failure reads cannot create the bubblewrap … namespace instead.
Where the sandbox capability probe runs¶
tclaude’s sandbox refuses rather than falling back, and that promise is only as good as the pre-flight probe behind it. On Linux the probe and the launch used to stand in different places, so on some hosts the probe could pass a launch that could not run.
The two places. The probe is reached from tclaude session new: a child of
tclaude agentd for a dashboard spawn, or of your shell for a CLI launch. The
process that really execs bwrap is several hops away — tmux server → pane
bootstrap shell → dir-proof guard shell → exit-gate shell → (whenever the
launch has a cgroup) session resource-limit-exec → tclaude …
tclaude-layer-winch-relay → bwrap — and the tmux server inherits its
confinement from whatever first auto-started it. Any per-process confinement
that differs between the two (an AppArmor profile per binary, an SELinux
domain, a seccomp filter, a differing no_new_privs) is invisible to a probe
that never runs under it.
What tclaude does now. When a tmux server is already running, the probe is
executed through it: tmux run-shell forks the same tclaude capability
probe from the server, one sh and one tclaude exec away from bwrap, so a
profile transition keyed on either executable applies to the probe exactly as
it will to the launch. A passing posture is remembered briefly (keyed on the
server pid, so a restart re-asks, and expiring on its own so a prerequisite you
remove stops being reported as present); a failing one is never remembered, so
installing the missing capability takes effect on the next launch.
The hops are close, not identical. The launch also crosses the guard and gate shells and, whenever the launch has one, a per-session cgroup that a tmux job does not join — so a confinement expressed as cgroup policy is not reproduced by this probe. What it reproduces is the per-process confinement inherited from the tmux server, which is the case observed.
When no tmux server is running yet, the probe runs in-process. That is usually
exact rather than merely safe: this process is the one that will auto-start the
server, so its confinement is the one the pane inherits. The exception is a
profile that transitions on the tmux binary itself (/usr/bin/tmux Px -> tmux,
or an SELinux type_transition), which puts the server in a domain the
launching process is not in.
When the probe cannot reach the server, it says so. If the round trip
cannot be made — the staging path is unreachable because agentd runs under
systemd PrivateTmp=yes while tmux does not, the confined server cannot write
it, the job publishes nothing — tclaude falls back to probing in the preparing
process and logs a warning naming the reason. Nothing is refused on a failed
round trip, so without that line a permanently disabled probe would look
exactly like the original bug. If you are debugging "why did it not refuse?",
that warning is the first thing to grep for.
The residual cases still fail closed at the pane. A confinement that changes
between probe and launch, a tmux server that restarts under a different
profile, or any of the fallbacks above can still leave the exec denied. The
relay reports that denial as a named refusal —
tclaude’s sandbox requested — refused: the host denied this process permission to
execute bubblewrap … — instead of the bare fork/exec …: operation not
permitted at exit 125 it used to print. Nothing runs unconfined; but the pane
dies rather than being refused pre-flight, so this is evidence that names the
cause, not a restored pre-flight contract.
Symptom → cause¶
| Symptom | Likely cause |
|---|---|
| Files written, exit 0, gone next command | Silent write under a deny (Linux bubblewrap) |
command not found for a tool on $PATH |
Install root under a deny and not reopened |
| Builds fail despite readable caches | Toolchain binary root denied, not just the cache |
tclaude: command not found, socket fine |
tclaude's binary dir not reopened — it is never implicit |
| Git loses identity / credential helper | ~/.gitconfig not reopened — add a file row for it (needs tclaude’s sandbox on Linux) |
unsupported_sandbox_profile_file_grant |
A row names a file on an implementation that cannot bind one — use tclaude’s sandbox on Linux |
…was a regular file when this rule was authored and is now a directory |
The pathname a file row named was replaced by a directory; re-author the row if that is intended |
git add -A: "can only add regular files" |
Claude Code masks a denied path with a /dev/null device node — stage specific paths |
Launch refused, …reopen_under_deny |
Claude Code not sandbox on, or Codex not Linux managed-profile with a verified probe |
could not resolve a trusted bubblewrap (bwrap) |
A group/world-writable component above bwrap — see an untrusted bwrap |
Pane dies instantly, refused: the host denied this process permission to execute bubblewrap |
The tmux server's confinement forbids the exec — see where the probe runs |
| Profile looks strict, nothing is denied | Claude Code sandbox inherit/off — the deny rows are emitted but the sandbox never engages |
Agent read a denied path with the Read tool |
Expected under deny ~ — that shape reaches layer 1 only |
| Agent reached something the profile denied | Check MCP, which bypasses the sandbox |
| Claude Code loses the model hours into a filtered session | A Claude subscription login refreshes its token at platform.claude.com; include net-anthropic (see Network filtering). The rotated token is written back to ~/.claude/.credentials.json from inside tclaude’s sandbox |
/config, /permissions, or /model write fails in the pane |
The harness-config floor — reopen the one path, or set harness_config: "write" |
See also¶
- Network filtering — the two egress engines, packs, and the unix-socket axis.
- Credential proxies — git, GitHub, and Linear without secrets in the sandbox.
- Spawning and lifecycle — the full spawn guardrail list.
- Processes › Run scope — program steps of an agent- or group-scoped process run execute inside the same layer, under the agent's or group's profiles, and fail closed when it is unavailable.
- Permissions and audit — the slug model behind
sandbox-profiles.manageandagent.sandbox-impl. - Claude Code sandboxing: https://code.claude.com/docs/en/sandboxing