skip to content

By default, what can a command inside Claude Code's Bash sandbox write, read and reach on the network?

level: middleimportance: must knowfreq 20%

answer

  1. writes narrow, reads wide
  2. working directory plus temp plus added dirs
  3. protected paths inside the write area
  4. allowedDomains starts empty
  5. proxy-unaware tools cannot connect

basics

~10 s

Writes: the working directory, a per-user temp directory and added directories, minus protected config paths. Reads: most of the machine, credential files included. Network: only through a local proxy whose allowedDomains list starts empty.

solid answer

~40 s

Writes are limited to the working directory and its subdirectories, a per-user temp directory (`$TMPDIR` points there) and directories added with `--add-dir`, `/add-dir` or `permissions.additionalDirectories`. Inside that area, **protected paths** stay write-denied: `.claude` settings, skills, agents, hooks, `.mcp.json`, shell startup files, `.gitconfig` and `.git/hooks`, and no `allowWrite` entry lifts them. Reads cover most of the machine, including `~/.ssh` and `~/.aws/credentials`, so you add `filesystem.denyRead` or `sandbox.credentials` entries yourself; there is no built-in credential deny list. Network traffic has no direct route out. It goes through a proxy on your machine that checks each hostname against `network.allowedDomains`, which starts empty, and your permission mode decides what happens to a new host. Tools that ignore the proxy variables, such as most database drivers and plain `ssh`, cannot connect even to an allowed host.

code

json · 16 lines
json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube"],
      "denyRead": ["~/.ssh"]
    },
    "network": {
      "allowedDomains": ["registry.npmjs.org", "*.example.com"]
    },
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "NPM_TOKEN", "mode": "deny" }]
    }
  }
}

go deeper

for a junior

Remember the shape: writes stay in the project and temp, reads are mostly open, and the network goes through an allowlist that starts empty.

for a middle

Explain protected paths, the narrower-path rule for denyRead and allowRead, and why a tool that ignores the proxy fails even for an allowed host.

for a senior

Close the read default for credentials explicitly, prefer allowWrite over taking a tool out of the sandbox, and watch for broad domains that open exfiltration paths.

for a principal

Weigh each widening against the other layer: a write grant can undo network limits later, and a broad domain can undo the read limits.

## Two layers, two different defaults The sandbox has two independent layers. **Filesystem isolation** decides which paths a sandboxed command may read and write. **Network isolation** decides which hosts it may reach. Their defaults lean in opposite directions: writes are narrow, reads are wide, and the network starts closed. Environment variables are a third thing to watch. Sandboxed commands inherit Claude Code's environment, secrets included, unless you scrub them. | Access | Default | Settings that change it | | --- | --- | --- | | Writes | Working directory, per-user temp dir, added directories; protected paths denied | `filesystem.allowWrite`, `filesystem.denyWrite` | | Reads | Most of the machine, including `~/.ssh` and `~/.aws/credentials` | `filesystem.denyRead`, `filesystem.allowRead`, `credentials` | | Network | No direct route; a proxy checks hostnames; allowed list starts empty | `network.allowedDomains`, `network.deniedDomains` | | Environment | Inherited, including secrets | `credentials.envVars`, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | ## Writes By default a sandboxed command can write to: - the **working directory** and its subdirectories; - a **per-user temp directory**, which Claude Code points `$TMPDIR` at for sandboxed commands, so tools that write temp files keep working; - directories added with `--add-dir`, `/add-dir` or `permissions.additionalDirectories`. When a tool such as `kubectl` or `terraform` needs one more location, add it with `sandbox.filesystem.allowWrite`. The command stays sandboxed, which beats taking the tool out of the sandbox altogether. Sandbox paths use normal conventions (`/tmp/build` is absolute, `~/.kube` is under home). That differs from Read and Edit permission rules, where `//path` is absolute. **Protected paths** are the exception inside the write area. A command that could edit Claude Code's own configuration could grant itself permissions or add a hook or MCP server that later runs outside the sandbox. So the sandbox denies writes to `.claude` settings files, the `.claude/skills`, `.claude/agents`, `.claude/commands` and `.claude/hooks` directories, and `.mcp.json` in the working directory and the directories above it. In the working directory it also denies shell startup files such as `.bashrc` and `.zshrc`, `.gitconfig`, `.vscode`, `.idea`, and `hooks` and `config` inside `.git`. Most of `~/.claude` and `~/.claude.json` are protected too. Neither an `allowWrite` entry nor an `Edit` allow rule exempts these paths. The only way to lift them is to turn off filesystem isolation entirely with `filesystem.disabled`. ## Reads Reads are **open by default**, credential files included. You narrow them yourself: - `filesystem.denyRead` blocks paths, and `filesystem.allowRead` re-opens part of a denied region. When rules overlap, the narrower path wins, so `denyRead: ["~/"]` with `allowRead: ["~/projects"]` leaves only `~/projects` readable. - `sandbox.credentials` lists credential files and variables with `"mode": "deny"`. File reads are blocked, and variables are unset before each sandboxed command runs. - `permissions.blockReadsOutsideWorkingDirectories` removes read access to home and mounted volumes without writing path rules. No credential is blocked automatically. If a path is not on your list, a sandboxed command can read it. ## Network A sandboxed command has **no direct route out**. On Linux and WSL2 it runs in its own network namespace; on macOS, Seatbelt blocks every connection except the one to the sandbox proxy. Claude Code runs that proxy on your machine and points commands at it through `HTTP_PROXY`, `HTTPS_PROXY` and `ALL_PROXY`. The proxy checks each hostname against your lists: 1. `network.allowedDomains` starts **empty**. Wildcards like `*.npmjs.org` are allowed, and an entry with no port covers every port. 2. For a host that is not allowed, the sandboxed command waits for a decision. In Manual mode you get a prompt. "Yes" allows the host for the session. "Yes, and don't ask again" saves a `WebFetch(domain:...)` allow rule, which the sandbox also honours. 3. `network.deniedDomains` blocks a host even when a wildcard would allow it. Three consequences matter in practice: - Tools that **ignore the proxy variables**, such as most database drivers and plain `ssh`, fail even when their host is listed, because there is no other route out. - **UDP, QUIC and ICMP** cannot leave at all. - An allowed hostname that resolves only to a local address, such as loopback or the `169.254.169.254` metadata endpoint, is refused unless you also list the IP address. The names `localhost` and `*.localhost` are the exception. ## A typical widening ```json { "sandbox": { "enabled": true, "filesystem": { "allowWrite": ["~/.kube"] }, "network": { "allowedDomains": ["registry.npmjs.org", "*.example.com"] }, "credentials": { "files": [{ "path": "~/.aws/credentials", "mode": "deny" }] } } } ``` Every widening has a cost. A write grant to a directory on `$PATH` or to a shell startup file can lead to code running outside the boundary later. A broad domain such as `github.com` can become an exfiltration path, because the proxy decides by hostname and does not inspect TLS by default.

  • A sandboxed `git merge` fails with `unable to unlink old` on a file under `.claude/skills`. Why, and what are your options?
    `.claude/skills` is a protected path, so the sandbox denies writes there even inside the working directory, and no `allowWrite` entry lifts that. Approve Claude's offer to retry the command outside the sandbox, or run the git command yourself in another terminal. If strict sandbox mode is on, there is no retry, so running it yourself is the only option.
  • Your database client cannot reach `db.example.com`, even though it is in `allowedDomains`. What is going on?
    The driver opens its own TCP connection and ignores the proxy variables, and a sandboxed command has no route except through the proxy, so the allowlist never applies. On Linux the error looks like `Network is unreachable`. The fix is to run that command outside the sandbox with a narrow `excludedCommands` pattern, ideally paired with an ask rule, and to review the script, because it then runs with your full access.

  • Sandboxed commands cannot read anything outside the project directory.
  • ~/.ssh and cloud credential files are blocked from reads by default.
  • An allowWrite entry can re-open .claude/settings.json for writes.
  • Listing a database host in allowedDomains lets the database driver connect.
  • allowedDomains comes with common package registries already allowed.
  • The sandbox strips secret environment variables by default.