Search guides, workflows, and reference pages.

Docs/Setup

Sandbox troubleshooting

The secure agent setup (secure-agent-setup.md) runs every Bash subprocess inside a sandbox: Seatbelt on macOS, bubblewrap on Linux, plus Claude Code’s filesystem / network allowlists. A correct sandbox restricts what the agent can read and where it can talk; an over-restrictive one breaks legitimate workflows in ways that look like unrelated bugs (“ssh-agent unreachable”, “address already in use”, “Cannot connect to Docker daemon”). This page is the catalog of those cases — the symptom you see, the root cause in the sandbox config, and the fix (a settings.json widening with a one-line rationale).

If you hit a sandbox-shaped failure not listed below, add it here in the same shape — the catalog grows by experience, not by prediction.

Two surfaces make these entries discoverable in-session so a future reader does not have to remember the catalog exists:

  • The setup-isolated-setup-doctor skill probes each catalogued failure mode on demand and links back to the matching entry. Invoke it when you suspect a sandbox restriction; it runs the full probe set even when only one is in question.
  • The Sandbox-error hint hook fires after every Bash tool call, pattern-matches the result for the literal error strings catalogued below, and prints a [sandbox-hint] … line pointing at the matching entry — so the catalog reference appears next to the error automatically.

When the catalog grows a new entry, extend both surfaces too: add a matching probe to the doctor skill, and add a matching match … hint=… branch to the hint hook. The catalog stays the source of truth; the doctor and the hook stay the discoverability layer.

Related:


Shape of each entry

Every entry follows the same four sections so a future reader can pattern-match quickly:

  1. Symptom — the exact error message text the agent (or the user, in a terminal) sees. Verbatim where possible so a grep into this page surfaces the matching entry.
  2. Root cause — which sandbox layer (Seatbelt / bubblewrap / Claude Code filesystem allowlist / network allowlist / permissions.deny) is blocking the call, and why the restriction exists.
  3. Fix — a concrete edit to ~/.claude/settings.json (or the adopter’s project-local .claude/settings.local.json, where that scope makes more sense) shown as a JSON snippet. Per-entry rationale so the widening is auditable.
  4. Notes — platform-specific path variants, alternative paths the same agent / runtime might use, when not to apply the widening.

SSH agent / Yubikey appears unreachable from inside the sandbox

Symptom

Any of:

sign_and_send_pubkey: signing failed for ED25519 "user@host": agent refused operation
Could not open a connection to your authentication agent.
ssh-add: error fetching identities for protocol 1: communication with agent failed
Permission denied (publickey).

…on git push, ssh user@host, ssh-add -l, or any operation that consults ssh-agent. The variant the user reports as “Yubikey badly detected” — the Yubikey is plugged in and works outside the sandbox, but the agent inside the sandbox can’t reach its socket.

Root cause

SSH_AUTH_SOCK is passed through the claude-iso clean-env wrapper’s whitelist (see secure-agent-setup.md → The clean-env wrapper), so the environment variable is set inside the sandbox. The socket path it points at is the missing piece: on macOS the path is typically /private/tmp/com.apple.launchd.*/Listeners, which is not in any allowRead entry; on Linux it is typically /run/user/<uid>/keyring/ssh or a gpg-agent variant, only the gpg-agent path of which is currently allowed (/run/user/*/gnupg/).

Without read access to the socket file, the agent’s ssh / git push subprocesses get Operation not permitted when they try to connect(2) the unix-domain socket — but the userland error surfaces as the “agent unreachable” / “Permission denied” strings above, which is what makes the cause non-obvious.

On Linux, path access is necessary but not sufficient. Recent Claude Code builds sandbox Bash with a seccomp filter that rejects socket(AF_UNIX, ...) outright, before any path is consulted, so no allowRead / allowWrite entry can make an agent reachable:

$ python3 -c 'import socket; socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)'
PermissionError: [Errno 1] Operation not permitted
# the same call with AF_INET succeeds, so this is not a path problem

Verified under bubblewrap with ~/.gnupg/ and /run/user/<uid>/gnupg/ in both allowRead and allowWrite: a signed git commit still fails with No agent running, and gpg-connect-agent cannot start one (exit status 2). Where that filter is active, an agent-dependent command — a signed git commit, git tag -s, ssh-add -l — must run with a per-call sandbox bypass, or outside the agent session entirely. The one setting that lifts the filter is sandbox.network.allowAllUnixSockets: true (allowUnixSockets is macOS-only, so it cannot name the agent socket here). It opens every socket the sandbox can see, not just the agent’s, so set it only together with the denyRead entries in Linux needs allowAllUnixSockets. The allowlist entries below remain correct and still matter (gpg reads the keyring through them); they simply do not restore the agent channel on their own.

On macOS, path access is likewise necessary but not sufficient. Seatbelt lets a sandboxed process stat(2) a socket whose path is in allowRead, but connect(2) to a Unix socket is a separate grant: sandbox.network.allowUnixSockets. With only the read entry the symptom is exactly the one above — the socket file is visible and the agent is “unreachable”:

$ ssh-add -l
Error connecting to agent: Operation not permitted
$ git commit …
error: No private key found for public key "~/.ssh/<key>.pub"?
fatal: failed to write commit object

(ssh-keygen -Y sign reports the unreachable agent as a missing private key — it found the public half, asked the agent for the private half, and got no answer.)

Fix

Two entries on macOS — the socket path has to be both readable and connectable — and one on Linux (see the AF_UNIX caveat above for what the read entry can and cannot do there). Add the socket to sandbox.filesystem.allowRead and, on macOS, to sandbox.network.allowUnixSockets:

// ~/.claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        // ...existing entries...
        "/private/tmp/com.apple.launchd.*/Listeners",   // macOS: system launchd-managed ssh-agent socket
        "/private/tmp/ssh-*/agent.*"                    // macOS: openssh-portable variant (rare)
        // Linux: `~/.gnupg/` and `/run/user/*/gnupg/` are already in the framework reference;
        // add `/run/user/*/keyring/` here if you use gnome-keyring or seahorse for SSH.
      ]
    },
    "network": {
      "allowUnixSockets": [                             // macOS only — ignored on Linux
        "/Users/<you>/.gnupg/S.gpg-agent.ssh"           // gpg-agent's ssh socket (enable-ssh-support); absolute path
        // "/private/tmp/com.apple.launchd.*/Listeners"   // instead, for the system ssh-agent
      ]
    }
  }
}

Per-entry rationale:

  • /private/tmp/com.apple.launchd.*/Listeners — Apple’s launchd manages per-session daemon sockets including the system ssh-agent. The wildcard * matches the launchd UUID; the Listeners directory holds the actual socket files. This is the default path on macOS.
  • /private/tmp/ssh-*/agent.* — fallback for openssh-portable running outside launchd (uncommon on stock macOS, sometimes seen with Homebrew-installed openssh).

Notes

  • If you use gpg-agent for SSH (enable-ssh-support in ~/.gnupg/gpg-agent.conf), the read side is already covered — the framework reference includes ~/.gnupg/ and /run/user/*/gnupg/, where S.gpg-agent.ssh lives. That is not enough on macOS: the socket also has to be listed in sandbox.network.allowUnixSockets, or connect(2) is denied and ssh-add -l reports the agent unreachable while the file is plainly there. On Linux, see the AF_UNIX caveat under Root cause: the read entries let gpg read the keyring, but do not by themselves make the agent socket reachable.
  • If you use Secretive (an alternative macOS Yubikey agent), the socket lives under ~/Library/Group Containers/<bundle>/socket.ssh; add that specific path to allowRead instead of the launchd glob.
  • Do not widen allowRead to /private/tmp/** — that opens the entire system temp directory, which other processes use for arbitrary files including credentials. Stay specific.
  • The socket grant makes signing work. Whether it also makes git push / git fetch over ssh work from inside the sandbox depends on the harness. A sandbox that routes network through its HTTP proxy only gives an ssh transport no DNS and no TCP — ssh: Could not resolve hostname github.com — before any key is consulted; push from your own terminal (the ! prefix in Claude Code runs a command there), or use an https remote, which does go through the proxy. A harness that exports a GIT_SSH_COMMAND whose ProxyCommand points ssh at its SOCKS proxy changes the symptom, not the outcome, as long as that proxy wants credentials nc cannot offer — This proxy requires authentication, and this client did not offer an authentication method (Claude Code on macOS, 2026-09). Where the transport does get through and the key’s aut slot carries a touch policy (the recommended setup leaves it Off; gpg.format=ssh needs it on), it then asks the key for its authentication touch — a git pull that hangs with no error is usually that, and the touch overlay covers it.
  • If git signs with gpg.format=ssh, the agent socket is only half of it: git also has to read the public key file, which the sandbox denies along with the rest of ~/.ssh/. That is its own entry — Signed commit fails before any touch when git signs with ssh.

Signed commit fails before any touch when git signs with ssh

Symptom

git commit with commit.gpgsign=true and gpg.format=ssh fails at once — no touch is requested, the hardware-key touch overlay never appears — and git reports:

Couldn't load public key /Users/<you>/.ssh/<key>.pub: No such file or directory
fatal: failed to write commit object

The tell is the timing. A signature the key is actually waiting on takes the key’s full touch window (~15 s) before it gives up with agent refused operation; this fails in well under a second. The same deny reads differently from a plain head -c 1 <that file> in a sandboxed Bash — Operation not permitted — which is what the doctor probe and verify check report; ssh-keygen sees the hidden path as missing.

Root cause

Filesystem allowlist. With gpg.format=ssh, git does not sign through gpg at all: it runs ssh-keygen -Y sign -f <user.signingkey> -n git, and user.signingkey names the public key file under ~/.ssh/. The framework’s permissions.deny carries Read(~/.ssh/**), which the sandbox mirrors as a read deny on the whole directory, so ssh-keygen cannot open the file. The agent socket (the entry above) is the separate requirement that lets the private half sign; this entry is about the public half git must read first.

Fix

Allow that one file — and only that file — for reads:

// ~/.claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        // ...existing entries...
        "~/.ssh/id_ed25519_sk.pub"   // the file `git config --get user.signingkey` prints
      ]
    }
  }
}

Per-entry rationale: it is the public key, which is not a secret by definition; the private key stays on the token or in the agent. Never widen this to ~/.ssh/ — that directory also holds private keys, config and known_hosts.

Notes

  • Find the exact path with git config --get user.signingkey. With a hardware key that is the .pub file; the agent holds the private half.
  • permissions.deny’s Read(~/.ssh/**) stays as it is. That rule governs the agent’s own Read tool, which has no business in ~/.ssh/; sandbox.filesystem.allowRead only widens what Bash subprocesses may open.
  • The hardware-key touch overlay (secure-agent-setup.md → Hardware-key touch overlay) cannot flag this: it watches for ssh-keygen blocking on the key, and here ssh-keygen exits before it ever blocks. If the overlay never shows for a commit that fails instantly, check this entry before suspecting the overlay.
  • Linux: the AF_UNIX caveat in the entry above still applies on top of this one.

Signed commit fails with “cannot exec” of the touch-overlay wrapper

Symptom

Every git commit the agent runs fails at the signature, instantly, after the touch overlay’s wrapper has been installed as git’s signing program (secure-agent-setup.md → From your own terminal):

fatal: cannot exec '/Users/<you>/.claude/scripts/gpg-touch-wrap-ssh-keygen': Operation not permitted
error:
fatal: failed to write commit object

Or, when the wrapper itself could be started but the script behind it could not be read (see the symlink note under Fix):

error: bash: /Users/<you>/.claude/scripts/gpg-touch-wrap-ssh-keygen: Operation not permitted
fatal: failed to write commit object

The same commit from your own terminal works, and signs with the window up. A git pull or git push over ssh fails the same way when core.sshCommand names the wrapper: fatal: cannot exec '…/gpg-touch-overlay.sh wrap ssh' or a bare Permission denied from the shell that tries to start it.

Root cause

Filesystem allowlist. gpg.ssh.program (gpg.program, core.sshCommand) is global git config, so the git the agent runs inside the sandbox reads it too and tries to start the wrapper. The wrapper lives in ~/.claude/scripts/, and the sandbox denies reads under ~/.claude/ wholesale — the interpreter cannot open the script, and git reports the exec failure. Nothing about the key or the agent socket is involved: the failure is one directory earlier.

Inside the sandbox the wrapper would do nothing anyway — it stands aside in an agent session (CLAUDECODE=1) and only runs the real program — but it has to be readable to get that far.

Fix

Allow the two wrapper files — the script and the symlink git names — for reads, and nothing else under ~/.claude/:

// ~/.claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        // ...existing entries...
        "~/.claude/scripts/gpg-touch-overlay.sh",
        "~/.claude/scripts/gpg-touch-wrap-ssh-keygen"   // or gpg-touch-wrap-gpg with OpenPGP signing
      ]
    }
  }
}

The symlink and its target are both listed because the sandbox resolves the path git opens and the path the interpreter then reads separately. The window scripts next to them need no entry: the wrapper never reaches them from inside the sandbox.

If your ~/.claude/scripts/ entries are themselves symlinks — into a dotfile sync repository, the layout secure-agent-setup.md → Syncing user-scope config across machines recommends — the grant must name the real file, because the sandbox checks the resolved path: with ~/.claude/scripts/gpg-touch-overlay.sh -> ~/.claude-config/scripts/gpg-touch-overlay.sh, list ~/.claude-config/scripts/gpg-touch-overlay.sh as well. The tell is the second form of the symptom: git starts the wrapper, and it is bash: that reports Operation not permitted on the script. readlink -f ~/.claude/scripts/gpg-touch-wrap-ssh-keygen prints the path to grant.

Per-entry rationale: these are two framework-authored scripts the operator installed by hand; no credential, no configuration of the agent’s own lives in them. Never widen this to ~/.claude/scripts/ or ~/.claude/ — the latter holds the agent’s settings, hooks and session state.

Notes

  • The verify skill’s check 10d and the doctor’s signing-key probe both report the wrapper unreadable before a commit trips over it.
  • Until the grant is in place, a one-off git -c gpg.ssh.program=/usr/bin/ssh-keygen commit … signs without the wrapper; the hook still arms the window for the agent’s commit.
  • The failure is the mirror image of the previous entry: there git could not read the key file, here it cannot read the program. Both fail in well under a second, before the key is asked for anything.

Signed commit fails with the agent refusing, and the overlay never appeared

Symptom

A git commit the agent runs gets through every pre-commit hook and then dies at the signature, with a write error from the wrapper immediately before it and no touch window at any point:

error: /Users/<you>/.claude/scripts/gpg-touch-wrap-ssh-keygen: line 340: /tmp/magpie-gpg-touch/watcher.pid: Operation not permitted
Signing file /tmp/claude-<uid>/.git_signing_buffer_tmpXXXXXX
Couldn't sign message (signer): agent refused operation?
fatal: failed to write commit object

The same commit succeeds when run outside the sandbox, or from your own terminal.

Root cause

The overlay keeps its owners registry, window lease, pid and log files in $XDG_RUNTIME_DIR/magpie-gpg-touch. macOS sets no XDG_RUNTIME_DIR, and the fallback used to be /tmp, which is outside the sandbox’s write set. The wrapper cannot create its pid file, so no watcher starts; nothing puts a window on screen; the key is never touched; and gpg-agent gives up with agent refused operation.

The error names the watcher, not the key, which is what makes this read like a broken signing setup rather than a sandbox denial.

Fix

Update the framework. The fallback is now ${XDG_CACHE_HOME:-$HOME/.cache}/magpie-gpg-touch, which is per-user, not world-writable, and inside the reference allowWrite, so the watcher starts under the sandbox with no widening.

A stale /tmp/magpie-gpg-touch/ left by an older version is harmless and can be removed.

Do not point the overlay at $TMPDIR instead. It differs between the signing contexts that have to find one another — the agent’s hooks see the harness’s scratch directory, a terminal git sees the login one — and two contexts computing two runtime directories cannot share an owners registry or a window lease.

Notes

  • The /tmp fallback was also a local-security weakness independent of the sandbox: /tmp is world-writable, so another user on the machine could pre-create the directory and sit on the pid files and the lock the window is leased through.
  • Distinct from the two entries above: there git could not read the key or could not exec the wrapper, and both failed instantly. Here the wrapper runs, the signature is genuinely attempted, and the failure arrives only once the agent stops waiting for a touch that was never prompted for.

Test cannot bind to a localhost port

Symptom

[Errno 13] Permission denied
[Errno 49] Can't assign requested address
OSError: [Errno 98] Address already in use   # red herring when sandbox-related

…from a test that starts a fixture server (pytest with live_server, requests-mock, an integration test spinning up a local HTTP listener, a webhook fixture). The same test passes outside the sandbox.

A second shape fails one step earlier, on the bind(2) call itself, before any client connects:

OSError: [Errno 1] Operation not permitted

…on every address (127.0.0.1, localhost, 0.0.0.0, ::1), with no allowedDomains change making any difference. The doctor skill’s localhost-bind probe reports it as ✗ (bind: [Errno 1] Operation not permitted).

Root cause

Claude Code’s sandbox.network block is allowlist-based on outbound hosts (egress to named domains), not on inbound binds. For most listener types this is fine — bind(2) on 127.0.0.1 doesn’t go through the network namespace at all on macOS, and on Linux loopback is allowed by default.

The case that bites is a test that needs to talk to its own server over the loopback interface: the test binds (works), the test’s HTTP client then tries to GET http://127.0.0.1:NNNN/ (may fail), because the sandbox’s network allowlist does not include 127.0.0.1 or localhost and the egress proxy treats it as a disallowed destination.

The “Permission denied” / “Address already in use” texts the test runner surfaces are its own framework’s generic error strings, not the sandbox’s — which makes the root cause hard to spot.

The bind(2) refusal is a different gate. Newer Claude Code sandbox profiles deny listening sockets outright unless sandbox.network.allowLocalBinding is true; the framework reference .claude/settings.json does not set it, so a listener is refused before the egress proxy is ever involved. Adding localhost / 127.0.0.1 to allowedDomains does not help this shape, because no outbound connection is being attempted yet.

Fix

For the bind(2) refusal, enable local binding. It is a boolean, so the last settings file that sets it wins; the per-project .claude/settings.local.json is the right place when only some repos run fixture servers:

// <adopter-repo>/.claude/settings.local.json
{
  "sandbox": {
    "network": {
      "allowLocalBinding": true                         // let sandboxed processes listen on a port
    }
  }
}

allowLocalBinding permits listen(2) on the host’s interfaces; it does not add any outbound destination, so the egress allowlist is unchanged. Once binding works, the loopback GET below may still fail — apply both fixes when the probe reports both.

For the loopback-GET failure, add localhost and 127.0.0.1 to the network allowlist:

// ~/.claude/settings.json
{
  "sandbox": {
    "network": {
      "allowedDomains": [
        // ...existing entries...
        "localhost",                                    // local fixture servers, test webhooks
        "127.0.0.1"                                     // same; IP form for tests that use it directly
      ]
    }
  }
}

Per-entry rationale:

  • localhost / 127.0.0.1 — loopback only. Adding these does not widen the egress surface (no traffic leaves the host); it just lets the sandbox proxy stop treating loopback as a disallowed destination.

Notes

  • For tests that need an outbound port (e.g. an integration test that listens on a port and then a separate process connects from outside the test’s own runtime), localhost is not enough — you need to allow the actual remote IP in allowedDomains. Those are project-scope concerns; add to .claude/settings.json in the adopter repo rather than the user-scope file.
  • If a test is genuinely incompatible with the sandbox (e.g. it expects raw socket access to a privileged port), the per-call escape hatch is dangerouslyDisableSandbox: true in the Bash tool call — but that surface should be visually loud (the sandbox-bypass-warn.sh hook ensures it is). Prefer the allowlist fix above when applicable.

Docker / Podman command fails with a socket error

Symptom

Cannot connect to the Docker daemon at unix:///Users/<user>/.docker/run/docker.sock. Is the docker daemon running?
ERRO[0000] error connecting to /var/run/docker.sock: open /var/run/docker.sock: operation not permitted
Cannot connect to Podman. Please verify your connection to the Linux system using `podman system connection list`
Error: unable to connect to Podman socket: failed to read identity "/Users/<you>/.local/share/containers/podman/machine/machine": operation not permitted
dial unix ./.apache-magpie-local/run/podman.sock: connect: no such file or directory
dial unix ./.apache-magpie-local/run/podman.sock: connect: operation not permitted

…on any docker / podman / nerdctl invocation. The first three lines are the CLI reaching straight for the real daemon socket or the podman machine’s ssh identity, both denied by design. The last two are the CLI reaching the container gateway’s own socket instead. no such file or directory means the gateway is not running for this project. operation not permitted means its socket is not in sandbox.network.allowUnixSockets (macOS), or that sandbox.network.allowAllUnixSockets is not true (Linux).

Inside the sandbox, podman machine list prints an empty table even when the machine is running, because the machine directory under ~/.local/share/containers/podman/machine/ is unreadable. An empty list from inside the sandbox is therefore not evidence that no machine exists. Check the machine’s real state from outside the sandbox (a !-prefixed shell command, or your own terminal) before assuming it needs podman machine init.

Root cause

The container daemon socket is root-equivalent over whatever the daemon mounts: a default Podman machine mounts /Users, /private, and /var/folders read-write, and Docker Desktop’s daemon is no narrower. Neither excluding docker / podman from the sandbox with sandbox.excludedCommands, which some upstream guidance suggests, nor listing the daemon socket itself in sandbox.network.allowUnixSockets is acceptable for that reason: both hand the agent unrestricted host access through the daemon. The framework’s sandbox-lint tool enforces the second half of that. It rejects any allowUnixSockets entry whose basename is docker.sock, podman.sock, or ends in -api.sock, unless the entry’s parent directory is the gateway’s run directory: <project>/.apache-magpie-local/run or <git-common-dir>/apache-magpie/run/<worktree-id>.

On macOS, the podman CLI’s default connection to a Podman machine goes over ssh://, using an identity file under ~/.local/share/containers/podman/machine/, a path the framework’s blanket ~/ read denial already covers. The machine’s actual API socket lives elsewhere, under $TMPDIR/podman/<machine>-api.sock (podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}' prints the exact path), not under ~/.local/share as the ssh identity path might suggest.

The supported route is the container gateway. It runs outside the sandbox, holds the only connection to the real daemon socket, and exposes two policy-checked sockets of its own in its run directory: <project>/.apache-magpie-local/run/ for a project that has adopted Magpie, and <git-common-dir>/apache-magpie/run/<worktree-id>/ for one that has not (git rev-parse --git-common-dir prints the common directory; it is the main checkout’s .git, also from a linked worktree). Below, <run-dir> is whichever of the two applies. <worktree-id> is main for the main working tree and the <name> of .git/worktrees/<name> for a linked worktree (it must match [A-Za-z0-9._-]+), so each worktree has its own gateway and sockets. CONTAINER_HOST and DOCKER_HOST point at podman.sock and docker.sock in that directory, only those two sockets are ever added to allowUnixSockets, a SessionStart hook starts the gateway when a session begins, and a PreToolUse hook starts it again before a container command if it exited mid-session. See Container gateway in the setup guide for the full install.

Fix

Error line Cause Action
failed to read identity "…/machine/machine": operation not permitted CONTAINER_HOST / DOCKER_HOST are unset, so the CLI fell back to its default connection instead of the gateway Add the reference env block below to .claude/settings.local.json
dial unix /.//.apache-magpie-local/run/podman.sock — note the leading /.// CONTAINER_HOST / DOCKER_HOST use a project-relative unix://./… value, which the CLIs do not resolve against the cwd Use the absolute unix:///<project>/… spelling in the env block below
dial unix /<run-dir>/podman.sock: connect: no such file or directory The gateway is not running for this project. It exits after its idle timeout (4 h), when another session on the project ends, or when it crashes; the PreToolUse ensure hook restarts it before the next container command, so this error means that hook is not wired or could not start it Wire the ensure hook per Container gateway, run ~/.claude/scripts/container-gateway-hook.sh start </dev/null from a terminal in the project root (the hook reads its payload from stdin; with none it uses the current directory), or check <run-dir>/container-gateway.log for why it did not start
dial unix /<run-dir>/podman.sock: connect: operation not permitted The gateway is running but its socket is missing from sandbox.network.allowUnixSockets (macOS), or allowAllUnixSockets is off (Linux, where the seccomp filter blocks every AF_UNIX socket) Add both gateway sockets as absolute paths, per Container gateway; on Linux set allowAllUnixSockets with its denyRead entries, per Linux needs allowAllUnixSockets
no podman or docker backend found; nothing to serve in the gateway log, while podman works by hand On macOS the gateway asked podman machine inspect for the socket path, and that command renders it from the caller’s TMPDIR Update the framework: discovery now also probes getconf DARWIN_USER_TEMP_DIR/podman/, so a hook whose TMPDIR differs from the machine’s still finds the socket
// .claude/settings.local.json (gitignored, per machine — NOT committed)
{
  "env": {
    "CONTAINER_HOST": "unix:///<run-dir>/podman.sock",
    "DOCKER_HOST": "unix:///<run-dir>/docker.sock"
  }
}

A unix:// URL’s authority is parsed as a host component, so every relative spelling misses the socket — unix://./x dials /.//x, unix://x dials /x/, and unix:x dials //. unix:///absolute/path is the only form that connects (verified against podman 6.1.0), which is why this block is per-machine rather than committed.

403 container-gateway: …

A request that reaches the gateway but fails its policy comes back as 403, and the CLI prints the message verbatim, for example container-gateway: bind-mount: /Users/you/.ssh is outside the allowed roots (…); see docs/setup/sandbox-troubleshooting.md#docker--podman-command-fails-with-a-socket-error. The message names the rule that refused the request, and it points back at this very catalog entry. The full create-time refusal table lives in tools/container-gateway/README.md → What the policy refuses. Adjust the request rather than widening the sandbox: a 403 from the gateway is the policy working as intended, not a sandbox misconfiguration. One refusal is not a 403: an inspect of a container, pod, volume or network whose name is not one of the project’s resources answers 404, whether the name is missing or another project’s, with the same message. Clients probe for a name that way and carry on only after a 404, so an untyped docker inspect <image>, which asks for a container of that name first, then finds the image.

A tool that drives the CLI for you can hide that message, by capturing the CLI’s output or by calling an HTTP-upgrade endpoint, for which the CLI prints only the status (unable to upgrade to h2c, received 403). The gateway logs every refusal as a deny <method> <path>: <reason> line in <run-dir>/container-gateway.log, so read the reason there.

Some workflows cannot pass the gateway, however the request is adjusted:

  • BuildKit. docker buildx build, and docker build wherever buildx is its default, talk to the builder over POST /grpc and /session, a gRPC stream the gateway cannot inspect, so it refuses both (deny POST /grpc: unknown-endpoint). A buildx docker-container builder container is label-checked like any other resource and is refused when it does not carry the project label (label-check on buildx_buildkit_default).
  • The daemon socket inside a container. A tool that bind-mounts DOCKER_HOST’s socket into its own container is refused, since the run directory is never a bind source.

Apache Airflow’s breeze, for example, runs into both. Excluding it from the sandbox is no way past them, for the reason given under Root cause above.

An agent that meets such a refusal stops and reports it to the user, with the deny lines from the log. It does not route around it: no other socket, no sandbox bypass, and no switch to a workflow the project’s own instructions rule out, such as running tests on the host when they say to use the project’s container tooling. The user decides, for example to run the tool from their own terminal.

Notes

  • The gateway’s docker-backend discovery on macOS reads the current docker context from the CLI’s own files (~/.docker/config.json and the context store), so it works with a docker CLI from Homebrew or Docker Desktop, neither of which is on the hook’s fixed PATH. Colima’s socket lives under ~/.colima/<profile>/docker.sock, and a Colima context already set as active is picked up the same way as Docker Desktop’s, with no Colima-specific configuration. A socket file is used only when something answers on it: a Docker Desktop socket left behind after Desktop stopped is skipped rather than served. Discovery runs once, when the gateway starts, so start Docker Desktop or Colima before the session; a runtime started later is not picked up until the gateway is restarted, and until then the log says no podman or docker backend found; nothing to serve. With DOCKER_CONFIG set, the CLI’s files are read from that directory instead of ~/.docker, as the CLI does. If the gateway log names a backend you did not expect, check docker context ls from your own terminal and restart the gateway after switching.
  • The gateway’s podman-backend discovery on Linux reads $XDG_RUNTIME_DIR/podman/podman.sock directly, which is rootless Podman’s default socket location, again with no separate configuration.
  • Do not widen allowRead to ~/.docker/**. The directory holds auth tokens and saved contexts, and the whole point of the framework’s Read(~/.docker/**) denial is to keep those out of the agent’s reach.
  • Docker Desktop’s CLI binary and plugins need read access, independently of which socket the CLI talks to. docker on PATH is ~/.docker/bin/docker, a symlink into /Applications/Docker.app, and docker compose / docker buildx are separate binaries under ~/.docker/cli-plugins/. The framework’s sandbox.filesystem.allowRead includes both as exact paths, so a settings file derived from it runs them out of the box; the rest of ~/.docker stays denied. If yours predates that and fails with operation not permitted: docker or unknown command: docker compose, add ~/.docker/bin/ and ~/.docker/cli-plugins/ to it. With docker installed via Homebrew, the CLI lives on a normal PATH directory outside ~/.docker, and the two entries are harmless no-ops.
  • If no Podman machine exists, or it is stopped, run podman machine init / podman machine start from your own terminal, outside the sandbox. Verify the result from outside the sandbox too: per the Symptom note above, podman machine list run inside the sandbox reports an empty table regardless of the machine’s real state.
  • When only Podman is installed, the gateway still serves the docker CLI. DOCKER_HOST points at the gateway’s docker.sock, which relays to whichever backend it found, so docker ps and friends work through Podman’s Docker-compatible API alone.
  • For CI / image-build workflows that run inside an adopter repo and need a wider gateway configuration than the reference default (e.g. --extra-bind-root on container-gateway serve, or any other project-specific sandbox allowance), prefer project scope (.claude/settings.local.json in the adopter) over user scope. That keeps the framework’s user-scope reference minimal and makes the widening visible to whoever audits the adopter’s repo — a rule that holds for any workflow-specific sandbox widening, not just this one.
  • If the doctor’s container probe reports gateway source at ~/.claude/scripts/container-gateway/src is not readable inside the sandbox, the gateway may well be running: the probe cannot ask it for its status. That happens in a project with no .apache-magpie/ snapshot when its gateway wiring lacks the read grant; add ~/.claude/scripts/container-gateway/ to sandbox.filesystem.allowRead in .claude/settings.local.json, alongside the allowUnixSockets entries. It is a read grant only; never add that directory to allowWrite, which would make the hook refuse the source.

Temp files fail with “Read-only file system” under /tmp

Symptom

$ mktemp -d
mktemp: failed to create directory via template '/tmp/tmp.XXXXXXXXXX': Read-only file system

$ touch /tmp/scratch
touch: cannot touch '/tmp/scratch': Read-only file system

Python and other runtimes surface the same restriction through tempfile:

OSError: [Errno 30] Read-only file system: '/tmp/tmpXXXXXXXX'

Root cause

The sandbox mounts the host /tmp read-only and punches only specific subpaths writable — Claude Code’s own scratch tree under /tmp/claude-<uid>/ plus anything listed in sandbox.filesystem.allowWrite. Anything writing to /tmp directly is refused.

Most tooling honours $TMPDIR and therefore lands inside the writable tree without noticing. The failure shows up when either:

  • TMPDIR is unset or has been overwritten (a login shell, an env -i wrapper, a Makefile that clears the environment), so the runtime falls back to the hardcoded /tmp; or
  • TMPDIR names a path outside sandbox.filesystem.allowWrite.

A second, quieter failure mode: TMPDIR points at the shared session root rather than a per-project directory, so concurrent sessions in different repos write temp files into the same directory and can collide on identical filenames.

Fix

For the unset / overwritten and outside allowWrite cases above, point TMPDIR back at a directory inside the writable tree for whatever cleared it — the env -i wrapper, the Makefile, the login shell — at that call site. /tmp/claude-<uid>/ is already inside the sandbox’s writable set, so nothing needs widening.

For the shared-session-root case there is currently no fix. Setting env.TMPDIR in the project’s .claude/settings.local.json — which this entry recommended until recently — does not work:

// <adopter-repo>/.claude/settings.local.json
{
  "env": {
    // Accepted, and silently without effect. Do not rely on it.
    "TMPDIR": "/tmp/claude-<uid>/<path-slug>/shared"
  }
}

Claude Code sets TMPDIR itself when it builds the sandbox, to the shared session root /tmp/claude-<uid>, and that assignment wins over the settings value. The override is specific to TMPDIR: other env keys from the same file do take effect, so a session can show a live CONTAINER_HOST from project settings and a TMPDIR that ignores them. The symptom of having tried is a directory that exists, is named exactly as configured, and stays empty for the life of the setting.

In practice the collision risk this case describes is mostly absorbed elsewhere: each session also gets its own scratchpad under /tmp/claude-<uid>/<path-slug>/<session-id>/, which is per-project and per-session by construction. Prefer that for anything a skill or tool writes; treat a bare $TMPDIR as shared with every other project on the machine, and make temp filenames unique rather than assuming the directory is yours.

Notes

  • env is applied at session start. For the keys that are honored, a change does not take effect in the session that makes it; restart, then confirm with the doctor skill’s project-scratch probe. TMPDIR is not one of those keys — see the Fix above.
  • The scratch directory cannot be remapped onto literal /tmp inside the sandbox. sandbox.filesystem.* accepts allow / deny path lists only — there is no bind-mount or path-remap key. sandbox.bwrapPath swaps the bwrap binary, not its flags, so it cannot inject --bind, and it is honored only from admin-controlled managed settings. Seatbelt exposes no profile-injection surface either. TMPDIR is the supported lever.
  • Independently of that ceiling, mounting over /tmp would hide Claude Code’s own IPC endpoints that live there (cc-daemon-<uid>, claude-http-*.sock) and would likely break the session.
  • Do not widen allowWrite to /tmp as a whole — that opens the entire system temp directory, which other processes use for arbitrary files including credentials.

gh fails with TLS OSStatus -26276 or HTTP 401 inside the sandbox

Symptom

Either of:

Get "https://api.github.com/user": tls: failed to verify certificate: x509: OSStatus -26276
HTTP 401: Requires authentication (https://api.github.com/graphql)

…from a gh call made through the Bash tool, while gh auth status reports a healthy login and the very same command succeeds in a terminal. Which of the two appears depends on the call: on macOS the TLS variant is the common one; the 401 is the keyring token read failing silently, so gh sends the request unauthenticated.

Root cause

gh is a Go binary. On macOS Go hands TLS certificate verification to Security.framework, and gh reads its token from the keychain through the same framework. Both go over mach services (trustd, securityd) that the Seatbelt profile does not expose, so verification fails with errSecServiceNotAvailable (-26276) and the token read returns nothing. The CONNECT proxy and the certificates are fine — Python’s urllib through the same proxy returns 200 — and nothing on the Go side can route around the framework: the Homebrew gh does not embed Go’s fallback root store, so GODEBUG=x509usefallbackroots=1 is inert, and Go ignores SSL_CERT_FILE on darwin. Claude Code exposes no setting for mach services (enableWeakerNetworkIsolation is about the proxy, not the trust store).

That is why the framework reference runs gh outside the sandbox with sandbox.excludedCommands: ["gh *"] (secure-agent-setup.md). The symptom above means this particular gh did not get excluded. The exclusion is decided per Bash invocation, and it holds only when every segment of the command is cd … or gh …. Measured on macOS 26 with Claude Code 2.1.278:

Command shape Runs outside the sandbox?
gh api user --jq .login yes
cd /repo && gh pr view 12 --json title yes
gh pr view 12 --json title && gh pr diff 12 yes
gh api … | head -1 no
gh api … > "$TMPDIR/out.json" (any redirection, even alone) no
x=$(gh api …) no
for n in 1 2; do gh pr view "$n"; done no
sh -c 'gh …', uv run … vetted-op-read … (gh as a child process) no
gh search issues "\`x\`" or gh pr create --body '`x`' (a backtick anywhere, even escaped or single-quoted) no

Claude Code’s documentation says the exclusion list is matched against each && / | / ; segment independently; in practice a single non-gh segment, or any redirection, keeps the whole invocation inside the sandbox. So does a backtick anywhere in the command string, even one the shell would leave literal (escaped, or inside single quotes): the match treats it as a command substitution (measured on Claude Code 2.1.280). A Markdown PR or issue body passed inline with --body hits this, since its code spans are backticks.

Fix

This one is not a settings widening — there is nothing to widen. Two parts:

  1. Keep gh on the exclusion list (already in the framework reference):

    // ~/.claude/settings.json (or the adopter's .claude/settings.json)
    {
      "sandbox": {
        "excludedCommands": ["gh *"]   // gh needs the keychain + Security.framework; run it outside
      }
    }
  2. Shape every gh invocation so the exclusion applies:

    • make gh the only kind of command in the invocation — cd … && gh …, or several gh … && gh …;

    • do the post-processing with gh’s own --jq / --template instead of a pipe into jq, head, or python3;

    • batch many reads into one GraphQL query with aliased fields (a: pullRequest(number: 1){…} b: pullRequest(number: 2){…}) rather than a loop;

    • for writes that need a JSON body, write the file in a separate non-gh call and pass it with --input file.json — reading a file is fine, only shell redirection breaks the match;

    • pass Markdown titles and bodies from a file — --body-file for gh pr create, gh issue create and gh pr comment, --input for gh api — never inline, because a backtick in the command breaks the match;

    • to capture a large payload to a file, move the redirection inside gh with a shell alias, so the Bash command stays a single gh … part. Import once from a YAML file (gh alias import aliases.yml):

      tofile: |-
        !out="$1"; shift
        case "$out" in
          *..*) echo "gh tofile: refusing a path containing ..: $out" >&2; exit 2 ;;
          /private/tmp/claude*|/tmp/claude*|"$PWD"/*|[!/]*) ;;
          *) echo "gh tofile: refusing to write outside the working directory or the Claude scratch tree: $out" >&2; exit 2 ;;
        esac
        exec gh "$@" > "$out"

      then gh tofile "$TMPDIR/pr.json" pr view 12 --json title,body runs excluded and a separate non-gh call reads the file. The path guard matters: the alias runs outside the sandbox, so without it any gh tofile could overwrite any file the user can write. This is tracked upstream as anthropics/claude-code#95532; drop the alias once a fixed release no longer treats a redirection as a non-matching part;

    • for a loop or pipeline that genuinely cannot be reshaped, run that one call with the per-call sandbox bypass and say so (the bypass-visibility hook makes it loud).

Notes

  • The same -26276 hits every other tool that verifies TLS through Security.framework; the framework runs lychee in offline mode for exactly this reason (see the annotated .claude/settings.json in secure-agent-setup.md).
  • Any wrapper that spawns gh as a child — sh -c, a Makefile target, the vetted-ops dispatcher — is matched on its command string, not on gh. Add the wrapper’s invocation to excludedCommands too, alongside its permissions.allow rule; the two gates are independent and both key on the command string.
  • The Monitor tool runs its command sandboxed and has no bypass flag, so a gh-based CI poll loop is blind. Use the Bash tool with run_in_background plus the per-call bypass instead.
  • Do not work around this by dumping the token (gh auth token) into GH_TOKEN; the framework reference keeps that command in permissions.deny on purpose.
  • A different symptom with a similar smell — the excluded gh works but prompts on every call, gh pr view included — is a permissions problem, not a sandbox one: a catch-all Bash(gh *) in permissions.ask (any scope; ask rules merge from every settings file). Claude Code evaluates deny, then ask, then allow, and a matching ask rule prompts even when a more specific allow rule also matches. Replace the catch-all with the explicit write-subcommand list from the reference .claude/settings.json; the verify skill’s check 11b fails on it and the doctor’s gh probe warns.
  • Linux / bubblewrap is not measured here. Go uses its own root store on Linux, so the TLS half does not apply; the keyring half depends on which credential helper gh is configured with.

prek or uv not found, or cannot write its cache, inside the sandbox

Symptom

$ prek run --all-files
(eval):1: command not found: prek

$ uv run pytest
(eval):1: command not found: uv

A binary reached by absolute path gets further and then fails writing its cache or state under ~/.cache/ or ~/.local/share/uv/. git config --global --get <key> printing nothing inside the sandbox, while it prints the value in a terminal, is the same failure on ~/.gitconfig.

Root cause

Claude Code filesystem allowlist. The framework’s committed .claude/settings.json lists ~/.local/bin/, ~/.local/share/uv/, ~/.cache/, ~/.gitconfig and ~/.config/git/ under sandbox.filesystem.allowRead (and ~/.cache/ writable under allowWrite), carving them out of denyRead: ["~/"]. The harness does not apply those project-scope entries: the effective sandbox denies every one of them, while the same kind of entry in .claude/settings.local.json or ~/.claude/settings.json takes effect. It is the behaviour behind issue #197, where the committed "." entry was dropped the same way. The Claude Code documentation says allowRead merges across every scope, so treat this as harness behaviour that may change, not as a contract.

Fix

Re-run the project-root helper. It writes the dev-tool paths, as absolute paths, into the gitignored project-local file, beside the project root it already adds:

~/.claude/scripts/sandbox-add-project-root.sh --all-worktrees
// <adopter-repo>/.claude/settings.local.json (written by the helper)
{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        "/home/<you>/code/<repo>",
        "/home/<you>/.gitconfig",          // git's user.name / user.email
        "/home/<you>/.config/git",         // git's per-host config
        "/home/<you>/.cache",              // uv / prek / ruff / mypy caches
        "/home/<you>/.local/share/uv",     // uv's tool venvs (prek)
        "/home/<you>/.local/bin"           // uv-installed entry points
      ],
      "allowWrite": [
        "/home/<you>/code/<repo>",
        "/home/<you>/.cache"
        // never ~/.local/share/uv: see the next entry
      ]
    }
  }
}

The helper writes that file only from outside the sandbox (it is in the harness’s write-deny set). The harness re-reads it without a restart: the next sandboxed command already sees the new paths. Confirm with prek --version, or with the doctor skill’s dev-tools probe.

Notes

  • The helper deliberately does not mirror the whole committed allowRead. That list also names credential paths (~/.config/apache-magpie/, ~/.gnupg/), which the same harness behaviour currently keeps out of sandboxed Bash. Re-open one of those only for the tool that needs it, per the entries above.
  • --no-tool-paths keeps the old behaviour (project root only) for an operator who does not run prek or uv in agent sessions.
  • Do not reach for dangerouslyDisableSandbox: true to run prek: its hooks execute code from the working tree, and the sandbox is what keeps a compromised hook away from the rest of $HOME.

uv python install or uv tool install fails inside the sandbox

Symptom

A sandboxed uv python install, uv tool install, or a uv run / prek run that needs an interpreter not installed yet, fails writing under ~/.local/share/uv/ with Operation not permitted (macOS) or Read-only file system (Linux). Commands that use an interpreter or tool already installed keep working.

Root cause

Deliberate. ~/.local/share/uv/ holds the interpreters and tool venvs that hooks, MCP servers, the excluded uvx / uv run commands and your own terminal run outside the sandbox, so the sandbox may read it but not write it (Host-only uv state). Older versions of sandbox-add-project-root.sh granted the write; the current one removes it, and so does magpie-setup’s session-start hook the next time a session opens in the project.

Fix

Run the install from a terminal, outside the sandbox:

uv python install 3.13
uv tool install prek

Do not add ~/.local/share/uv back to allowWrite: sandbox-lint rejects it.

The same switch moved sandboxed prek to its own home, ~/.cache/prek-sandbox (env.PREK_HOME), so the first sandboxed prek run after it rebuilds its hook environments once; that is expected, not a failure.

Notes

  • Path variants. uv keeps this state under $XDG_DATA_HOME/uv/ when XDG_DATA_HOME is set, and under UV_PYTHON_INSTALL_DIR or UV_TOOL_DIR when those are; the error then names that directory instead, and the fix is the same. The error text differs by platform only: Operation not permitted from Seatbelt on macOS, Read-only file system from bubblewrap on Linux.
  • The interpreter download path. A sandboxed uv run or prek run hits this too when the project asks for a Python that is not installed, because uv tries to download one into the same directory. Install that version from a terminal (the one the project’s requires-python or .python-version names) and re-run.
  • Do not work around it by moving the directory. Pointing UV_PYTHON_INSTALL_DIR or UV_TOOL_DIR at a path the sandbox can write recreates the problem the restriction prevents: interpreters and tools that run outside the sandbox would again be writable from inside it.
  • The hint hook recognises it. sandbox-error-hint.sh matches a write failure under share/uv/ and points here.

Git hooks silently skipped for commits made inside the sandbox

Symptom

Nothing, which is the problem: a git commit run by the agent succeeds without pre-commit (and so without prek), commit-msg or any other hook having run, and CI is the first place the skipped checks fail. Asked directly, git inside the sandbox cannot see the hook:

$ git hook run pre-commit
error: cannot find a hook named pre-commit

$ ls ~/.claude/git-hooks
ls: cannot access '/home/<you>/.claude/git-hooks': No such file or directory

The same commands in a terminal find the hook.

Root cause

Claude Code filesystem allowlist. Whole-user scope sets git config --global core.hooksPath ~/.claude/git-hooks, and the sandbox read-denies the home directory apart from the paths granted back. Git inside the sandbox finds no hook directory, and git treats a missing hook as “nothing to run”, so it neither fails nor warns. Per-project scope is not affected: its hooks live in the repository’s own .git/hooks/, which is inside the project root.

Fix

Grant the shared hook directory, read-only, in user-scope settings, where core.hooksPath itself lives:

// ~/.claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        "~/.claude/git-hooks/"   // core.hooksPath: sandboxed git runs pre-commit, commit-msg, ...
      ]
    }
  }
}

When the hooks are symlinks into the sync repository, add ~/.claude-config/git-hooks/ as well: the sandbox checks the resolved path. Confirm with git hook run pre-commit from the agent.

Notes

  • In the session that adds the grant, a new directory under ~/.claude/ may stay hidden until Claude Code is restarted, even where other grants take effect on the next command.
  • The dispatcher flavour also runs ~/.claude/scripts/sandbox-add-project-root.sh from post-checkout; ~/.claude/scripts/ is granted already for the other hooks.
  • There is no error text to match, so the error-hint hook cannot point here. The doctor skill’s git-hooks probe and setup-isolated-setup-verify check 8 look at the directory from inside the sandbox instead.

lefthook install refuses with “Custom hooks paths are not supported by default”

Symptom

A repository that uses lefthook has no working hooks, and lefthook install fails:

$ lefthook install
core.hooksPath is set globally to '/Users/<you>/.claude/git-hooks'
Custom hooks paths are not supported by default.
...

Root cause

Whole-user scope sets a global core.hooksPath, and lefthook refuses to install while a scoped git config --global read returns one. That is the safe failure: the alternative, --force, writes lefthook’s hook into the shared directory and replaces the framework’s dispatcher for every repository on the host.

Fix

Run lefthook install through the framework shim, which hides the global config from that read and leaves the hook in the repository’s own $(git rev-parse --git-common-dir)/hooks/:

~/.claude/bin/lefthook install

With ~/.claude/bin ahead of the real binary on PATH, plain lefthook install does that already. The setup installs the shim only for a repository that uses lefthook: a root lefthook.*, .lefthook.* or -local config, or an installed hook mentioning call_lefthook.

Notes

  • Do not run lefthook install --reset-hooks-path or --force to get past the error: the first unsets the whole-user setup, and the second overwrites the dispatcher for every repository. The agent-guard lefthook-hooks-path guard blocks both, in the --flag and --flag=true spellings, and needs MAGPIE_ALLOW_LEFTHOOK_HOOKS_PATH=1 to proceed deliberately.
  • An npm postinstall runs node_modules/.bin/lefthook, which the shim does not cover; that install refuses for the same reason, and the repository needs one run through the shim.
  • The shim hides the global config only while it holds a core.hooksPath, so on a host without one the install keeps the operator’s credential.helper, url.*.insteadOf and safe.directory.
  • Per-project scope has no global core.hooksPath, so the refusal does not happen there.

CaptainHook’s Composer plugin replaced the shared hook directory

Symptom

After a composer install or composer update, commits stop running the repository’s own hooks, or a repository that never had CaptainHook starts failing on hooks it did not configure. ~/.claude/git-hooks/ holds a CaptainHook-generated pre-commit and an old-hooks/ directory instead of the framework’s dispatcher symlinks.

Root cause

The captainhook/hook-installer Composer plugin (or the older captainhook/plugin-composer) runs the install on every dependency update. It does not go through ~/.claude/bin/captainhook, so the shim cannot point it at the repository’s own hooks, and it writes into the shared core.hooksPath directory behind the dispatcher.

Fix

Disable the plugin in the repository’s composer.json, reinstall the dispatcher, and run CaptainHook’s install through the shim once:

// composer.json
"extra": {
  "captainhook": { "disable-plugin": true }
}
# restore the dispatcher symlinks, then install into the repo's own hooks
cd ~/.claude/git-hooks
for h in post-checkout pre-commit prepare-commit-msg commit-msg \
         post-commit pre-push post-merge post-rewrite \
         pre-rebase pre-merge-commit; do
  ln -sf git-hook-dispatcher.sh "$h"
done
~/.claude/bin/captainhook install

The shim falls back to <repository root>/vendor/bin/captainhook when the binary is not on PATH, so the last command works from anywhere in the Composer project. A global captainhook on PATH wins over the project’s pinned one.

Notes

  • An install through the shim warns on stderr when composer.json requires either plugin and neither extra.captainhook.disable-plugin nor config.allow-plugins turns it off, so the next update does not undo the fix silently.
  • setup-isolated-setup-verify check 8 reports a repository with the plugin enabled as a warning, and install Step P.3b offers to add disable-plugin before installing the shim.

Reads of ~/.claude/magpie or /tmp/claude-<uid> ask for approval every time

Symptom

Every read of a temporary clone or file under the scratch root, or of the vetted-ops tree, stops for approval. A bulk sync that fans out into read-only gatherer agents raises one prompt per read per agent. The Read tool’s refusal reads:

/tmp/claude-1000/… is outside <repo>; the permissions.blockReadsOutsideWorkingDirectories setting blocks reads outside the working directories.

Root cause

Not the sandbox: Claude Code’s permissions.blockReadsOutsideWorkingDirectories setting. When it is on, a read of any path outside the session’s working directories asks first, whatever the allow rules say. The adopter repository is a working directory; the fixed vetted-ops path and the scratch root are not.

permissions.additionalDirectories takes literal paths. A glob such as /tmp/claude-* is accepted, and even listed as a working directory, but it is never matched.

Fix

For the scratch root, re-run ~/.claude/scripts/sandbox-add-project-root.sh --all-worktrees from a terminal (or with the sandbox bypass, as the setup skills do). It adds the directory as a resolved absolute path to each worktree’s project-local, gitignored .claude/settings.local.json:

"permissions": {
  "additionalDirectories": [
    "/tmp/claude-1000"              // "/tmp/claude-$(id -u)", resolved
  ]
}

Nothing becomes writable that was not before: the scratch root is already writable to sandboxed Bash.

Do not list ~/.claude/magpie there, and the helper removes it where an earlier version added it. The sandbox makes every working directory writable to sandboxed Bash, and the vetted-ops commands that run from that checkout are excluded from the sandbox, so a writable checkout lets sandboxed code change what runs outside it. sandbox-lint fails on such an entry. Reads of the vetted-ops tree keep prompting while the read block is on; the vetted-ops commands need it off anyway (see the notes below). Rationale: Working directories under the read-outside-working-directories block.

Notes

  • For one session, /add-dir <path> does the same without a settings change, and carries the same write consequence: never add ~/.claude/magpie that way either.
  • A Bash command that spells the path with a literal ~ still stops with … names '~/.claude/magpie/vetted-ops', which cannot be checked against the read block, even with the directory listed or an allow rule matching: the check does not resolve ~ inside a command. Every vetted-ops command is spelled that way, so where the dispatcher is used the only fix is to turn blockReadsOutsideWorkingDirectories off. That is required, not optional: a background gatherer agent cannot answer the prompt, so each one is a silent denial. See Read-only vetted ops never prompt.
  • The prompt comes before any command runs, so the sandbox-error hint hook never sees it. setup-isolated-setup-doctor probe 9 and setup-isolated-setup-verify check 15 detect it instead.
  • Keep the entries out of the committed project settings and out of a user-scope ~/.claude/settings.json synced across machines: both paths name this host’s home directory and uid.

Every Bash call fails with bwrap: Can't create file … Read-only file system

Symptom

Every Bash tool call fails before the command runs, whatever the command, with:

bwrap: Can't create file at <project>/.claude/settings.json: Read-only file system

The path named is one of the files the sandbox protects from writes (.claude/settings.json, .mcp.json, a shell rc), inside a directory that sandbox.filesystem.allowWrite lists.

Root cause

Linux only. A sandbox.filesystem.allowRead entry that is a parent of an allowWrite path — allowRead: ["/home/<you>/repos"] next to allowWrite: ["/home/<you>/repos/<project>"], under the reference denyRead: ["~/"] — makes bubblewrap mount the parent read-only on top of the writable child. The write path ends up read-only, and bubblewrap’s first step, creating a placeholder for each write-protected file that does not exist yet, fails, so the whole command fails. The mount order is Claude Code’s; the trap is in the settings shape.

Fix

Never list a parent of an allowWrite path in allowRead. List the specific directories you need read instead:

{
  "sandbox": {
    "filesystem": {
      "allowRead": [
        // not "/home/<you>/repos"
        "/home/<you>/repos/<project>",
        "/home/<you>/repos/<other-project>"
      ],
      "allowWrite": ["/home/<you>/repos/<project>"]
    }
  }
}

A parent that is itself in allowWrite is fine. sandbox-lint rejects an allowRead entry that is a strict parent of an allowWrite entry and not writable itself.


git status shows files you never created, such as .mcp.json or .bash_profile

Symptom

Inside the sandbox, git status lists untracked files that are not there when you look from your own terminal — typically .claude/settings.json, .mcp.json, or .bash_profile. stat shows they are not regular files:

$ stat -c '%F %t,%T' .mcp.json
character special file 1,3

Root cause

Device 1,3 is /dev/null. On Linux the sandbox protects a write-denied path that does not exist on the host — the agent settings files, .mcp.json, shell rc files — by bind-mounting /dev/null over a placeholder at that path, so a sandboxed command cannot create it. Git inside the sandbox sees the placeholder as a new file. An absent denyRead path gets no placeholder: there is nothing to hide, so nothing is mounted.

Fix

None needed: it is not a real file on the host. Do not commit it and do not delete it. Check from outside the sandbox (your own terminal) whether a real file is there before acting on it.

Writes to a tools/vetted-ops policy directory fail anywhere on disk

Symptom

Creating any file under a directory named .apache-magpie-overrides/tools/vetted-ops/ (or the personal-layer equivalents under .git/…/apache-magpie/, .svn/apache-magpie/ or .apache-magpie-local/) fails from inside the sandbox, even in a scratch directory:

PermissionError: [Errno 1] Operation not permitted: '/tmp/…/.apache-magpie-overrides/tools/vetted-ops'
error: unable to create file .apache-magpie-overrides/tools/vetted-ops/config.toml: Operation not permitted

The second line is a git checkout or git clone of a repository that commits its own policy there, such as apache/magpie itself.

Root cause

permissions.deny carries Edit(//**/.apache-magpie-overrides/tools/vetted-ops/**) and the personal-layer forms beside it, which Claude Code merges into the sandbox’s write deny. They match in every directory on purpose: vetted-op-read runs outside the sandbox without a prompt, and it uses the policy it discovers from the working directory without the approval the write dispatchers require. A policy the agent could plant under any directory would steer those unprompted reads at any repository the operator’s gh can see.

Fix

Leave the deny as it is. Work around the path instead:

  • A checkout of a repository that commits a policy: check it out from a terminal, or use a sparse checkout that leaves the policy directory out:

    git clone --no-checkout <url> <dir> && cd <dir>
    git sparse-checkout set --no-cone '/*' '!/.apache-magpie-overrides/tools/vetted-ops/'
    git checkout main
  • vetted-ops’ own tests: the tests that build a policy at one of these paths skip inside the sandbox, naming the path, and run in CI. Run the full suite from a terminal when you change discovery or approval.

  • Your project’s policy: edit and approve it from a terminal, as the vetted-ops README describes; the agent never writes it.

Notes

The deny is also why setup update and git pull in an adopter checkout can fail on a changed config.toml: pull from a terminal when the policy changes upstream.


Adding a new entry

When you hit a sandbox-shaped failure not in this list:

  1. Capture the exact symptom (error text, command, what you were trying to do). The error text is what makes the entry greppable for the next person.
  2. Identify the layer: filesystem (Operation not permitted on a path), network (refused / timed-out connection to an allowed host’s friend), or permissions.deny (the agent’s tool got an “I refuse” without the sandbox even being consulted).
  3. Find the minimal widening — the most specific allowRead / allowedDomains entry that resolves the symptom without opening adjacent paths. Stay as specific as the runtime reasonably allows; never widen ~/, /var/, or /private/ as a whole.
  4. Add an entry to this page in the Shape of each entry form above. Cross-reference adjacent entries when relevant.

If the fix involves dangerouslyDisableSandbox: true rather than a settings.json widening, document it here too — the bypass is a legitimate per-call escape hatch, but it should be visible in the catalog so future readers can see when it’s the right call.

Suggest a change