Claude Code sandbox mode, and what it breaks

What the Claude Code sandbox is

Anthropic's own description is worth reading closely, because it explains a behaviour people find surprising. The sandbox is a boundary the operating system enforces around the shell commands Claude runs, it applies to Bash, PowerShell and Monitor commands and to the processes they start, and because the operating system applies the limits while a command runs, Claude Code can run a sandboxed command without asking you to approve it first. In auto-allow mode, which is the default, the approval and the boundary are substitutes for each other: a command inside the wall does not need a conversation about whether to allow it.

It covers shell commands only. Claude's own file and web tools, meaning Read, Edit, Write, WebFetch and WebSearch, follow permission rules instead, so a denyRead entry does not stop the Read tool and allowedDomains does not limit WebFetch. Command hooks, local MCP servers, plugin monitors, LSP servers, your status line command and apiKeyHelper all run outside it with your full access. That is the first thing to be clear about: this is a wall around the shell, not a wall around Claude Code.

The enforcement is the operating system's, not a promise the model keeps. macOS uses Seatbelt, Linux and WSL2 use bubblewrap, and the whole thing is built on Anthropic's open source sandbox-runtime package. bubblewrap is the unprivileged sandboxing tool that enforces the filesystem isolation on Linux, and socat is the relay that routes a sandboxed command's network traffic through the sandbox proxy. On native Windows there is no sandbox at all: Claude Code runs commands unsandboxed there, and the documented route is to run Claude Code inside a WSL2 distribution.

Read that second row twice. The default lets a sandboxed command read credential files, and there is no built-in credential deny list, so only the files and variables you list in sandbox.credentials are restricted. If the point of turning the sandbox on is that a command cannot reach your keys, that part is still yours to configure.

The sandbox is off by default, and sandbox is unset until you write it. And it is not a permission mode. Permission modes decide whether a tool call runs and whether you are prompted first; the sandbox restricts what a Bash command can reach once it is already running. Anthropic states the distinction plainly, and the sandboxing page is where to read it in full.

How to turn on sandbox mode

There are two doors and they write to different places, which is the detail that confuses people later. /sandbox opens a panel and saves what you pick to the current project's .claude/settings.local.json, adding that file to your global gitignore when it does. Setting sandbox.enabled to true in ~/.claude/settings.json turns the sandbox on for every project instead.

1. Check that your platform can run it The sandbox runs on macOS, Linux and WSL2. On native Windows, Claude Code runs commands unsandboxed, and the documented route is to run Claude Code inside a WSL2 distribution.
2. Install what Linux needs On Linux and WSL2 the sandbox relies on bubblewrap and socat. Ripgrep ships with the native binary, and the seccomp filter is optional.
3. Open the panel with /sandbox It has Mode, Overrides and Config tabs, plus a Dependencies tab on Linux when the optional seccomp filter is missing; if only a Dependencies tab shows, a required package is missing.
4. Pick a mode Auto-allow runs sandboxed commands with no permission prompt. Regular permissions keeps the prompts even though the command is confined, and both modes enforce the same limits.
5. Confirm a command is confined Ask Claude to run touch ~/sandbox-probe. It fails with Operation not permitted on macOS, and with Read-only file system on Linux and WSL2.
6. Decide what to leave outside excludedCommands names the tools that cannot work under the sandbox. Every entry it matches runs with your full access, so keep each pattern as narrow as the job allows.

Type that probe command yourself and it proves nothing: a command you enter at the ! shell-mode prompt runs unsandboxed in most sessions. A second documented check works the same way. Ask Claude to run curl --noproxy '*' https://example.com and it fails with Could not resolve host, because the command has no route around the sandbox proxy. If Claude offers to retry a failed probe outside the sandbox, decline the retry.

The one-session form is worth knowing, because it is the tidy way to trial the sandbox. The documented example starts a sandboxed session in which Claude cannot retry a blocked command outside the sandbox: claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'.

One warning that belongs at the top. By default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. You get no failure and no wall. If you are turning the sandbox on because you want the wall, set sandbox.failIfUnavailable to true as well, and Claude Code exits at startup instead of running bare.

The panel fails loudly in the two cases worth recognising. It prints an error instead of opening when a higher settings level sets sandbox.enabled, sandbox.autoAllowBashIfSandboxed or sandbox.allowUnsandboxedCommands, and it prints Sandbox settings not changed when it cannot write to the project's .claude/settings.local.json, naming EACCES, EPERM or EROFS. Both mean your choice did not take effect, whatever the panel looked like.

The two sandbox modes, and the retry

Both modes enforce exactly the same filesystem and network limits. The only difference is whether a sandboxed command is approved automatically. Auto-allow is the default: autoAllowBashIfSandboxed is true, so a command inside the wall runs with no prompt. Set it to false and sandboxed commands go through the regular permission flow too, which the panel calls regular permissions mode.

Auto-allow is not a blanket. A command a Bash deny rule matches is still blocked, an rm or rmdir aimed at a critical path still goes through the permission flow, a content-scoped ask rule such as Bash(git push *) still prompts, and Monitor tool commands are not approved automatically even though they still run inside the sandbox.

The retry is the part that surprises people. When the sandbox blocks a connection, Claude Code names the denied host in the result, Claude reads that, and it may retry the command with the dangerouslyDisableSandbox parameter so the command runs outside the wall. Who approves that retry depends on your permission mode: it runs with no prompt in bypassPermissions mode, you get a prompt titled “Bash command (unsandboxed)” in Manual and acceptEdits modes, a separate classifier reviews it in auto mode, and dontAsk mode denies it.

There is one more way out that catches people. An allow rule that matches a command also approves its unsandboxed retry, so a rule broad enough to match can move a command out of the sandbox without anyone being asked.

To close that door, set allowUnsandboxedCommands to false. The panel calls this strict sandbox mode, and while it is on Claude Code ignores the dangerouslyDisableSandbox parameter entirely, so commands are sandboxed unless they match an excludedCommands entry.

One more mode fact matters for the network. In bypassPermissions mode a connection to a host outside your allowed domains is allowed without a prompt, and in dontAsk mode it is refused. A host listed in deniedDomains is refused in every mode. If you are running unattended, that rule is the difference between a sandbox that filters hosts and a sandbox that does not.

Why it breaks git

Three different things go wrong with git, and they do not have the same cause. The first is a write deny that git runs into while replacing a file. git merge, git checkout and similar commands fail with unable to unlink old when they need to replace a file the sandbox denies writes to, and on Linux and WSL2 the error ends with Read-only file system. The file is in one of three places: under a protected path, under one of your denyWrite entries, or outside the directories the sandbox lets commands write to at all.

The protected paths are worth knowing, because they are not your deny list and an allowWrite entry does not lift them. In your working directory and the directories above it the sandbox denies writes to the .claude settings files, the .claude/skills, .claude/agents, .claude/commands and .claude/hooks directories, .mcp.json, and the files Claude Code runs on its own. In your working directory only it denies shell startup files such as .bashrc and .zshrc, .gitconfig, .vscode, .idea, and hooks and config inside .git.

It also denies the HEAD, objects and refs entries that would turn your working directory into a bare repository, and most of ~/.claude including .credentials.json.

The second cause is network, and it is macOS only. git fetch, git pull and git push against an SSH remote fail inside the sandbox even when the host is allowed, because Claude Code tunnels git's SSH connection through the sandbox proxy and the macOS tunnel cannot authenticate to it. On Linux and WSL2 those commands work once the host is allowed. The documented fix on a Mac is to switch the remote to HTTPS, or to take git's network commands out of the sandbox.

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Those entries match git push origin main. A call that adds a cd, uses git -C, or contains a command substitution stays sandboxed, so this is not a general exemption for git. It is also worth being deliberate here: an excluded command reaches any host, not only the ones in allowedDomains.

The third cause is a report rather than a documented behaviour, and it is the one that wastes an afternoon. With the sandbox on, Claude Code puts placeholders at protected paths that do not exist in the project root. One person measured the consequences: git add . failed outright inside the sandbox with exit 128 and staged nothing, including legitimate files, while git status reported around nineteen phantom untracked files the model had no way to identify as sandbox artifacts.

Read that as a report from one setup, not as what every build does. Know the shape of it anyway, because an agent reasoning about phantom files is the expensive part.

Why it breaks gh and other Go tools on macOS

On macOS, tools such as gh, gcloud and terraform may fail TLS verification under Seatbelt. The documented fix is to add a pattern for each tool, such as gh *, to excludedCommands. The tool then runs with your full access and with its stored credentials, which is the trade you are making: you are not sandboxing that tool any more.

There is a softer option, and it only applies to one situation. If you are using httpProxyPort with a MITM proxy and a custom CA, set enableWeakerNetworkIsolation to true instead of excluding the tool. That keeps the tool inside the sandbox and weakens the network layer a little, which is the right order: widen the narrow thing before you remove the wall.

The reason it happens is not obvious from the error. Go on macOS verifies certificates through Security.framework, and the sandbox blocks those calls, so the failure is not about the certificate store and not about your token. That is exactly what one reporter measured: gh api user inside the sandbox returned tls: failed to verify certificate: x509: OSStatus -26276, Python's OpenSSL path worked in the same sandbox, and setting SSL_CERT_FILE, changing the CA bundle and switching to a token all failed to move it.

Why it breaks the network

A sandboxed command has no direct route to the network. On Linux and WSL2 it runs in a separate network namespace with no connection to yours, and on macOS Seatbelt blocks every connection except the one to the sandbox proxy. Claude Code runs that proxy on your machine, outside the sandbox, and points commands at it with HTTP_PROXY, HTTPS_PROXY and ALL_PROXY. The proxy checks the hostname of each connection against your allowed and denied domains.

That design splits every tool on your machine into two groups, and the split explains most of the failures people report. Tools that read the proxy variables, such as curl, npm and git over HTTPS, connect once their host is allowed. Tools that open their own connection, such as plain ssh and most database drivers, cannot connect even to a host in your allowed list. And anything that is not TCP cannot leave at all: UDP, HTTP/3 over QUIC, and ICMP tools such as ping.

The documented surface lists no setting that lets a tool in that second group reach a host on the network from inside the sandbox, and the one exception is a server on localhost on macOS, which the table below covers. For everything else the documented route is to run the command outside the sandbox, which the next section covers.

Allowed domains start empty, so the first time a command needs a new host Claude Code prompts in Manual and acceptEdits modes, and your permission mode decides in the others. Choosing Yes allows it for the rest of the session, and choosing “Yes, and don't ask again” saves a WebFetch(domain:...) allow rule to your local settings so it stays allowed. To avoid the prompt altogether, put the host in sandbox.network.allowedDomains. An entry with no port allows every port on that host, so the port is not what decides whether a connection gets through.

Loopback is stricter than most people expect. After a hostname passes the allowlist the proxy resolves it and refuses the connection when the name resolves only to a local address, which covers 127.0.0.1, link-local addresses such as the 169.254.169.254 metadata endpoint, and addresses assigned to your own machine. localhost and *.localhost are the documented exceptions allowed to resolve to loopback. A development name such as myapp.test that points at 127.0.0.1 is refused with a 403 whose body reads resolved to a loopback address, and the fix is to add the IP itself, with the port, next to the hostname.

Localhost has its own wrinkle. Claude Code sets NO_PROXY for sandboxed commands so a connection to localhost goes direct instead of through the proxy, which means an allowedDomains entry for localhost changes only the proxy path and not a direct one. On macOS, network.allowLocalBinding set to true lets a sandboxed command listen on ports and connect to any port on localhost. On Linux and WSL2 the key has no effect, because a sandboxed command's localhost is private to that command: it can reach servers it started itself, and never a server running on the host.

Docker gets its own line because the documentation gives it its own troubleshooting entry. docker is documented as incompatible with the sandbox, and the fix is an excludedCommands pattern such as docker compose *. A narrower pattern takes fewer commands out of the sandbox, so write the narrowest one that covers the job.

One report is worth reading beside that table, because it is the case where the documented fix did not hold. The reporter did not name an operating system, but they had allowLocalBinding on with localhost, 127.0.0.1 and ::1 all listed in allowedDomains, and their sock.connect() still returned EPERM against a service on their own machine. On macOS that setting is the documented answer for reaching a local server, so if this is your symptom the report is a reason to try an exclusion rather than assume you configured it wrongly. Their workaround was dangerouslyDisableSandbox or excludedCommands, and both of those take the command out of the sandbox entirely.

How to exclude a command

Excluding a command is the escape hatch the docs reach for most often, so it is worth understanding exactly what it does. An entry in sandbox.excludedCommands makes matching commands run with no filesystem restrictions and no network proxy. That is your full access, with the tool's stored credentials and its own routes. A broad entry such as docker * covers everything that tool can do, and Claude can write a script in your working directory and then run it outside the wall through a broad enough pattern.

The pattern syntax is the same as a Bash(...) permission rule, and the wildcard is where people get it wrong. A pattern with no wildcard is an exact match, so docker matches only docker with no arguments; end the pattern with * to match arguments as well. An entry takes a call out only when it covers every command in that call, so a docker * entry does not take npm ci && docker compose build out unless another entry covers npm ci.

Some call shapes stay sandboxed however you write the pattern. A call containing a cd, a redirection to a file, or a command substitution such as $(...) keeps the whole call inside the sandbox. So cd build && docker compose up stays sandboxed under a docker * entry, and adding a cd entry does not change that.

Two habits keep this honest. Write the narrowest pattern that covers the job, and read the pattern as an instruction: everything it matches runs with your full access, so a pattern that covers an interpreter or a script in your working directory is a larger grant than it looks.

What bwrap: execvp /bin/bash means

Read the message in two halves and it stops being cryptic. bwrap is bubblewrap, the tool that builds the sandbox on Linux and WSL2. execvp /bin/bash is bubblewrap saying it tried to start your shell inside the confined filesystem it had just assembled, and the system call failed. So the message does not mean your command was denied. It means the sandbox could not start the shell at all, which is why it hits every command, including echo hello.

Anthropic's troubleshooting list has a bubblewrap entry, but it is a different failure, so this message is not one the documentation names. The report that traces it is the useful source: on a merged-usr distribution, where /bin, /lib, /lib64 and /sbin are symlinks into /usr, the sandbox binds /usr into the new namespace without recreating those compatibility symlinks. The loader path a binary asks for, such as /lib64/ld-linux-x86-64.so.2, then does not resolve inside the sandbox and execvp returns ENOENT.

Debian, Ubuntu and Arch have shipped that layout for years, which is why the report calls it a large share of Linux and WSL2 users rather than an edge case.

Before you conclude that, rule out the causes the documentation does cover. First, check that bubblewrap and socat are installed, because the panel's Dependencies tab lists which of ripgrep, bubblewrap, socat and the seccomp filter your platform lacks, and it is the only tab shown while a required package is missing. Second, on Ubuntu 24.04 and later, check the AppArmor restriction: run sysctl kernel.apparmor_restrict_unprivileged_userns. A 0 or a missing key means this is not your problem; a 1 means the default policy is stopping bubblewrap from creating the user namespaces it needs, and the documented fix is an AppArmor profile for bwrap that grants them.

If you are inside a container rather than on a distribution, the error is different and the fix is documented. In an unprivileged container bubblewrap cannot mount a fresh /proc and sandboxed commands fail with a bwrap error such as Can't mount proc on /newroot/proc: Operation not permitted. Setting enableWeakerNestedSandbox to true makes the sandbox bind-mount the container's existing /proc instead. Use it only when the outer container already provides the isolation you need, because it exposes process information a fresh mount would have hidden.

If none of those match, the honest answer is that the merged-usr failure is a reported bug rather than a setting you got wrong, and it has been reported more than once. The documented surface lists no setting that repairs it, so the useful next step is the report itself rather than another configuration change.

One neighbouring Linux failure is worth recognising, because it looks like a sandbox bug and is not. Sandboxed commands cannot create user namespaces by default, so Chromium exits with No usable sandbox! and rootless Podman prints cannot clone: Operation not permitted. Start the browser with --no-sandbox, or exclude the command that launches it. For Chromium and Electron there is a third documented option: allowNestedUserNamespaces set to true in ~/.claude/settings.json. It needs Claude Code v2.1.305 or later and it turns off a security boundary, so read Anthropic's warning before you take it. It is not the answer for rootless Podman or Buildah, where the documentation says the setting alone is not enough and an excludedCommands entry is what to use.

What the sandbox is not

Anthropic is unusually direct about this, and the directness is useful. Sandboxing reduces risk but is not a complete isolation boundary. Effective sandboxing needs both layers: without network isolation a compromised agent could exfiltrate files such as your SSH keys, and without filesystem isolation it could backdoor something on the machine and use that to get network access. If you widen one side, check that the widening does not undo the other.

The network layer is a hostname check, not an inspection. By default the built-in proxy does not terminate or inspect TLS, so the contents of an encrypted connection are not examined, and Anthropic warns that allowing broad domains such as github.com can create paths for data exfiltration because the decision is made from the hostname the client supplied. If your threat model needs more than that, the sandbox environments page compares the built-in sandbox with a container or a virtual machine.

Two configuration choices widen it a lot. Allowing Unix sockets can grant access to services that lead to a bypass, and the documented example is that allowing /var/run/docker.sock effectively grants access to the host through the Docker socket. And since there is no built-in credential deny list, your credential files stay readable until you list them in sandbox.credentials.

Remember what is outside the wall in the first place. A command you type at the ! prompt runs unsandboxed in most sessions. Claude's file tools, hooks and MCP servers run outside it too. Subagents are a mixed case: they run in the same process as the parent session and use the same sandbox configuration, so a Bash command inside a subagent is sandboxed when the parent is, while a background session runs in its own process and is sandboxed only when its own settings enable it.

Two settings change the shape rather than the strength. sandbox.filesystem.disabled skips filesystem isolation and keeps network isolation, needs Claude Code v2.1.216 or later, defaults to false, and can only be set from user settings, managed settings or --settings, never from a project's settings files. And a sandboxed command gets a per-user temp directory as its $TMPDIR, so while filesystem isolation is on a sandboxed command and an unsandboxed one resolve $TMPDIR to different directories. Files passed between the two belong under the working directory.

What people have reported

Searching Anthropic's own issue tracker for issues with sandbox in the title on October 25, 2026 returns 941 issues. A few of them are worth reading before you turn the sandbox on, because each names a cost you would otherwise meet alone at eleven at night. Every report below is named by the person who filed it, with the day they filed it, and links to the issue.

That list is a report stream, not a changelog. An issue filed in February and still open does not by itself describe the build you are running, and a report is one person's setup rather than a statement about the product. Anthropic's own documentation is the reference for what the sandbox does now, and the four reports above are the reference for what it has cost people to find out.

Where Omniscio fits

Plainly: Omniscio has no setting for Claude Code's sandbox. It starts Claude Code sessions through the claude command line, so the sandbox keys Claude Code loads from your settings files are the ones that decide what a session's shell commands can reach. If you want the sandbox, set it in Claude Code, and nothing about it changes because the session was started from a desktop app.

What Omniscio does have is a different boundary, and it is worth not confusing the two. Per-session git worktree isolation gives a session its own copy of the project on its own branch, so two sessions running at once cannot overwrite each other's files. The sandbox limits what one session's shell commands can reach on the machine. One is about files, the other is about the machine, and neither replaces the other.

That copy is off by default on every switch, and you turn it on for one session, one project or the whole app. The one exception runs the other way: sessions on an engine whose tools run outside Claude Code's guardrail hooks start isolated by default in a git repository, because their tools never pass through Claude Code's own checks, and only an explicit per-session choice turns that off. A folder without git always runs in place. The library covers it in full.

Where Omniscio sits is at the sessions themselves. It is a desktop app for running Claude Code and other agent harnesses side by side, built around one calm inbox rather than a wall of terminals, where agents alert you only when a decision actually needs you. Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.

Two things worth knowing before you assume a default from that. The per-session spend cap is for metered model keys and Omniscio credits, and a subscription session on a Claude Pro or Max plan is never spend-capped. And the free plan covers 8 projects and 10 agents at once, with Pro at $20/month or $192/year.