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-doctorskill 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:
secure-agent-setup.md— full install walkthrough including the authoritative~/.claude/settings.jsonreference.secure-agent-internals.md— how each layer of the sandbox works and why.
Shape of each entry
Every entry follows the same four sections so a future reader can pattern-match quickly:
- 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.
- Root cause — which sandbox layer (Seatbelt / bubblewrap /
Claude Code filesystem allowlist / network allowlist /
permissions.deny) is blocking the call, and why the restriction exists. - 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. - 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 systemssh-agent. The wildcard*matches the launchd UUID; theListenersdirectory 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-supportin~/.gnupg/gpg-agent.conf), the read side is already covered — the framework reference includes~/.gnupg/and/run/user/*/gnupg/, whereS.gpg-agent.sshlives. That is not enough on macOS: the socket also has to be listed insandbox.network.allowUnixSockets, orconnect(2)is denied andssh-add -lreports the agent unreachable while the file is plainly there. On Linux, see theAF_UNIXcaveat 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 toallowReadinstead of the launchd glob. - Do not widen
allowReadto/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 fetchover 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 aGIT_SSH_COMMANDwhoseProxyCommandpoints ssh at its SOCKS proxy changes the symptom, not the outcome, as long as that proxy wants credentialsnccannot 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’sautslot carries a touch policy (the recommended setup leaves itOff;gpg.format=sshneeds it on), it then asks the key for its authentication touch — agit pullthat 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.pubfile; the agent holds the private half. permissions.deny’sRead(~/.ssh/**)stays as it is. That rule governs the agent’s own Read tool, which has no business in~/.ssh/;sandbox.filesystem.allowReadonly widens what Bash subprocesses may open.- The hardware-key touch overlay
(
secure-agent-setup.md→ Hardware-key touch overlay) cannot flag this: it watches forssh-keygenblocking on the key, and heressh-keygenexits 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_UNIXcaveat 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
/tmpfallback was also a local-security weakness independent of the sandbox:/tmpis 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),
localhostis not enough — you need to allow the actual remote IP inallowedDomains. Those are project-scope concerns; add to.claude/settings.jsonin 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: truein the Bash tool call — but that surface should be visually loud (thesandbox-bypass-warn.shhook 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, anddocker buildwherever buildx is its default, talk to the builder overPOST /grpcand/session, a gRPC stream the gateway cannot inspect, so it refuses both (deny POST /grpc: unknown-endpoint). A buildxdocker-containerbuilder 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 currentdocker contextfrom the CLI’s own files (~/.docker/config.jsonand the context store), so it works with adockerCLI from Homebrew or Docker Desktop, neither of which is on the hook’s fixedPATH. 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 saysno podman or docker backend found; nothing to serve. WithDOCKER_CONFIGset, 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, checkdocker context lsfrom your own terminal and restart the gateway after switching. - The gateway’s
podman-backend discovery on Linux reads$XDG_RUNTIME_DIR/podman/podman.sockdirectly, which is rootless Podman’s default socket location, again with no separate configuration. - Do not widen
allowReadto~/.docker/**. The directory holds auth tokens and saved contexts, and the whole point of the framework’sRead(~/.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.
dockeronPATHis~/.docker/bin/docker, a symlink into/Applications/Docker.app, anddocker compose/docker buildxare separate binaries under~/.docker/cli-plugins/. The framework’ssandbox.filesystem.allowReadincludes both as exact paths, so a settings file derived from it runs them out of the box; the rest of~/.dockerstays denied. If yours predates that and fails withoperation not permitted: dockerorunknown command: docker compose, add~/.docker/bin/and~/.docker/cli-plugins/to it. Withdockerinstalled via Homebrew, the CLI lives on a normalPATHdirectory 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 startfrom your own terminal, outside the sandbox. Verify the result from outside the sandbox too: per the Symptom note above,podman machine listrun inside the sandbox reports an empty table regardless of the machine’s real state. - When only Podman is installed, the gateway still serves the
dockerCLI.DOCKER_HOSTpoints at the gateway’sdocker.sock, which relays to whichever backend it found, sodocker psand 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-rootoncontainer-gateway serve, or any other project-specific sandbox allowance), prefer project scope (.claude/settings.local.jsonin 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 itsstatus. That happens in a project with no.apache-magpie/snapshot when its gateway wiring lacks the read grant; add~/.claude/scripts/container-gateway/tosandbox.filesystem.allowReadin.claude/settings.local.json, alongside theallowUnixSocketsentries. It is a read grant only; never add that directory toallowWrite, 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:
TMPDIRis unset or has been overwritten (a login shell, anenv -iwrapper, a Makefile that clears the environment), so the runtime falls back to the hardcoded/tmp; orTMPDIRnames a path outsidesandbox.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
envis 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.TMPDIRis not one of those keys — see the Fix above.- The scratch directory cannot be remapped onto literal
/tmpinside the sandbox.sandbox.filesystem.*accepts allow / deny path lists only — there is no bind-mount or path-remap key.sandbox.bwrapPathswaps 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.TMPDIRis the supported lever. - Independently of that ceiling, mounting over
/tmpwould 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
allowWriteto/tmpas 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:
-
Keep
ghon 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 } } -
Shape every
ghinvocation so the exclusion applies:-
make
ghthe only kind of command in the invocation —cd … && gh …, or severalgh … && gh …; -
do the post-processing with
gh’s own--jq/--templateinstead of a pipe intojq,head, orpython3; -
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-
ghcall 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-fileforgh pr create,gh issue createandgh pr comment,--inputforgh api— never inline, because a backtick in the command breaks the match; -
to capture a large payload to a file, move the redirection inside
ghwith a shell alias, so the Bash command stays a singlegh …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,bodyruns excluded and a separate non-ghcall reads the file. The path guard matters: the alias runs outside the sandbox, so without it anygh tofilecould 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
-26276hits every other tool that verifies TLS through Security.framework; the framework runslycheein offline mode for exactly this reason (see the annotated.claude/settings.jsoninsecure-agent-setup.md). - Any wrapper that spawns
ghas a child —sh -c, a Makefile target, thevetted-opsdispatcher — is matched on its command string, not ongh. Add the wrapper’s invocation toexcludedCommandstoo, alongside itspermissions.allowrule; the two gates are independent and both key on the command string. - The
Monitortool runs its command sandboxed and has no bypass flag, so agh-based CI poll loop is blind. Use the Bash tool withrun_in_backgroundplus the per-call bypass instead. - Do not work around this by dumping the token (
gh auth token) intoGH_TOKEN; the framework reference keeps that command inpermissions.denyon purpose. - A different symptom with a similar smell — the excluded
ghworks but prompts on every call,gh pr viewincluded — is a permissions problem, not a sandbox one: a catch-allBash(gh *)inpermissions.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
ghis 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-pathskeeps the old behaviour (project root only) for an operator who does not runprekoruvin agent sessions.- Do not reach for
dangerouslyDisableSandbox: trueto runprek: 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/whenXDG_DATA_HOMEis set, and underUV_PYTHON_INSTALL_DIRorUV_TOOL_DIRwhen those are; the error then names that directory instead, and the fix is the same. The error text differs by platform only:Operation not permittedfrom Seatbelt on macOS,Read-only file systemfrom bubblewrap on Linux. - The interpreter download path. A sandboxed
uv runorprek runhits 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’srequires-pythonor.python-versionnames) and re-run. - Do not work around it by moving the directory. Pointing
UV_PYTHON_INSTALL_DIRorUV_TOOL_DIRat 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.shmatches a write failure undershare/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.shfrompost-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-verifycheck 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-pathor--forceto get past the error: the first unsets the whole-user setup, and the second overwrites the dispatcher for every repository. The agent-guardlefthook-hooks-pathguard blocks both, in the--flagand--flag=truespellings, and needsMAGPIE_ALLOW_LEFTHOOK_HOOKS_PATH=1to proceed deliberately. - An npm
postinstallrunsnode_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’scredential.helper,url.*.insteadOfandsafe.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.jsonrequires either plugin and neitherextra.captainhook.disable-pluginnorconfig.allow-pluginsturns it off, so the next update does not undo the fix silently. setup-isolated-setup-verifycheck 8 reports a repository with the plugin enabled as a warning, and install Step P.3b offers to adddisable-pluginbefore 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/magpiethat 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 anallowrule 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 turnblockReadsOutsideWorkingDirectoriesoff. 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-doctorprobe 9 andsetup-isolated-setup-verifycheck 15 detect it instead. - Keep the entries out of the committed project settings and out of a
user-scope
~/.claude/settings.jsonsynced 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:
- 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.
- Identify the layer: filesystem (
Operation not permittedon a path), network (refused / timed-out connection to an allowed host’s friend), orpermissions.deny(the agent’s tool got an “I refuse” without the sandbox even being consulted). - Find the minimal widening — the most specific
allowRead/allowedDomainsentry that resolves the symptom without opening adjacent paths. Stay as specific as the runtime reasonably allows; never widen~/,/var/, or/private/as a whole. - 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.