Skip to content

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.
  • --sandbox is the harness's own sandbox mode — a per-harness setting.
  • --sandbox-impl is 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:

  1. Create a sandbox profile in the library, or use tclaude agent sandbox-profiles.
  2. Pick it under Sandbox profile in the spawn dialog, or set it for a group with 🛡.
  3. 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 plan shows 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 mode seatbelt). 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 pinning harness-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 mode off, Codex danger-full-access, Gemini CLI off via GEMINI_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-owned opencode serve executor; the attach pane stays outside. Requires bwrap and working unprivileged user namespaces on Linux; a missing capability refuses the launch — never a silent fallback — from whichever tier selected the layer. The bwrap found on PATH must also pass the trust walk described under An untrusted bwrap. On Linux the layer also creates and joins a per-launch cgroup even with no resource_limits authored: tclaude already owns and forks this workload, so the same accounting resource-only gives (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 a resource_cgroup_unavailable notice and the wall it asked for, where resource-only refuses. 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. With resource_limits authored you get CPU, memory and PID ceilings; without them you still get per-agent accounting (memory.peak, cpu.stat), host-OOM attribution (resource_limit_oom exit 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 a not_enforced notice. Remapped mount_path rules, 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 a resource_cgroup_unavailable notice instead (ceilings always fail closed).
  • off — the cross-harness explicit opt-out: each harness's native no-confinement posture (Claude Code and OpenCode off, Codex danger-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 setup records 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 set <agent> resource-only --restart

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 — the settings.json posture 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 | off only — deliberately no on, 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?} with access one of read | 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:
    • deny may 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, and resource-only/off all refuse with unsupported_sandbox_profile_file_grant.
  • Carve-outs work in both directions. A narrower row shadows a broader one: a narrow write reopens beneath a deny, and a narrow deny hides beneath an allow. This most-specific-wins shape is the whole strictness mechanism — see below.
  • mount_path — a read/write row 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. deny rows 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) and harness-builtin refuse the launch with unsupported_sandbox_profile_mount_path rather 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 a filesystem row 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. path is a sandbox path, so it is validated syntactically like mount_path and never resolved against the host; size takes 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 narrower read/write row still lands on top of it. What it may not do is claim a path a filesystem row 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 reason mount_path needs one; filesystem_root: separate is 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, and resource-only/off all refuse with unsupported_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 explicit read anywhere in the chain cannot be widened back to write by 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, TMUX and friends, plus the TCLAUDE_, CLAUDE_CODE_, CODEX_, LD_, and DYLD_ prefixes — with the single exception TCLAUDE_OFFLINE_MODEL.
  • agent_directories — environment-variable names bound to tclaude-materialized private per-agent directories.
  • filesystem_root — inherit prefers the read-only host root, separate requests the minimal constructed root even with open network, omitted means automatic derivation. Composes monotonically: separate anywhere in the chain wins, and inherit cannot weaken a rule whose enforcement itself requires a constructed root.
  • network — an authored baseline of inherit | allow | deny, allow/deny rows, packs, and a namespace selector (the legacy network_access: internet|none spelling 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|list plus path/path_glob entries (** 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 → cgroup memory.max, cpu (cores ≥ 0.01) → cpu.max at a 100 ms period, and pids (a whole count ≥ 1) → pids.max; Linux cgroup v2, whole workload tree, orthogonal to confinement, works with any non-off implementation. The PID ceiling bounds an exhaustion the other two do not — a fork bomb, an unbounded make -j, a tool loop leaking processes — and needs the delegated pids controller, which the documented Delegate=cpu memory does not carry: author one and the delegation needs Delegate=cpu memory pids, which the refusal names. All three blank means no cgroup probing at all, except under resource-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, and resource-only even 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.json carries the block tclaude setup --install-sandbox-hardening installs. Strip it and the wall around ~/.tclaude/data and ~/.claude/sessions is gone for every harness-builtin launch and for the human's own ambient claude.
  • ~/.codex/tclaude-agent.config.toml is the managed profile that provides Codex's harness-builtin confinement.
  • 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.rules pre-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:

  1. 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 ~/.claude write 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 under harness-builtin like any other file row.
  2. "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.
  3. --harness-config read|write at spawn time, for granting one agent the posture without authoring a profile for it:
tclaude agent spawn <group> --harness-config write

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:

tclaude agent sandbox-profiles harness-config-repairs

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, codex and claude with 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_PATH stays shared. The block just made $XDG_CACHE_HOME per-agent; without re-sharing the browser registry every agent would re-download hundreds of megabytes of browser bundles.
  • false, not exit 1. Letting the command fail trips tclaude's ERR trap, which names the block in the failure message; an explicit exit bypasses 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; closed dominates. Unix-socket lists intersect.
  • network.namespace: private and filesystem_root: separate compose monotonically — a later scope cannot widen them back to host/inherit.
  • network.engine is 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:

tclaude agent debug-export <agent> --file agent-debug.json

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 host tclaude source 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_contents row, 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:

tclaude agent spawn crew --name worker --sandbox-deny ~/secrets --sandbox-deny /srv/keys

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 off or resource-only, or a mode that omits the sandbox profiles (--omit-sandbox-profiles is 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, and allowedDomains: github.com, api.github.com). A kernel boundary — but it applies only to Bash commands and their children, not to the built-in Read/Write/Edit tools. That gap is verified: the Write tool created a file under ~/.tclaude/ on a machine whose Bash sandbox treated it as read-only.
  • Layer 2, permission rules (permissions.deny Read(…)/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.md or similar file in the harness config directory, and your next unsandboxed session reads it. See the harness-config floor.
  • ~/.claude/.claude.json stays writable, and it carries mcpServers. Under tclaude’s sandbox the harness-config floor cannot cover it: Claude Code writes that file continuously (project records, directory trust, history), and CLAUDE_CONFIG_DIR puts it inside the same writable state root. An agent that appends an mcpServers entry there gets that command executed by the next tclaude-launched Claude pane — including a harness-builtin one 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 ~/.gemini most of the dangerous ones are missing: .env, trusted_hooks.json, policy_integrity.json, GEMINI.md, and trustedFolders.json until --trust-dir first writes it. A walled Gemini agent can create ~/.gemini/.env (loaded into the environment of the operator's next gemini in a trusted folder: base URLs, GEMINI_SYSTEM_MD, NODE_OPTIONS) or a trustedFolders.json that trusts /. An empty placeholder is no fix for .env: Gemini stops at the first .env it finds, so an empty ~/.gemini/.env would 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.toml and <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/gh may 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-in Read tool 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/msgget take integer keys, and mq_open resolves its name against the IPC namespace's own internal mount rather than any path — /dev/mqueue only 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/cgroup naming agentd's delegated node and the session inside it, and it closes that fully only under a constructed root, which binds no /sys at all. Under the walking skeleton's recursive read-only host root, /sys/fs/cgroup is still mounted from the parent namespace — a cgroup namespace re-roots /proc/PID/cgroup and 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 under cgroup.procs. The -try spelling 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/cgroup reads 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-exec runs 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. ipcs shows 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 why docker run --ipc=host exists. Harmless for terminal-driven harnesses, which is what this layer wraps.
  • A nested tclaude run inside a sandbox sees 0::/ and cannot derive a delegated cgroup parent from it — when the cgroup namespace was created at all; see the best-effort note above. With no resource_limits authored 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) and internet use 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. internet therefore means more here than a tool-only Internet switch; the launch record calls this host network rather than repeating the profile word.
  • none requests 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); /dev and /proc are fresh, /tmp is tmpfs, and /run, /var, /srv, /media, /mnt, /boot, and /root are 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 /opt are mounted read-only, and a read-only mount does not block connect(), 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