Sandbox mode

Claude Code bash sandboxing on macOS, Linux, and WSL2; common settings and how sandboxing interacts with permissions.

Sandboxing isolates Bash (and child processes) using OS primitives: Seatbelt on macOS, bubblewrap on Linux and WSL2. It does not replace Read / Edit tools, which still follow permissions directly.

Concepts and workflows: Sandboxing. Configuration reference: Settings: Sandbox settings (table below is aligned with that page).

/sandbox in the CLI

Run /sandbox to open the interactive menu (modes, dependency hints on Linux). If the sandbox cannot start and failIfUnavailable is false, Claude Code warns and may run commands without the sandbox.

Prerequisites

Works out of the box.

Install bubblewrap and socat (see the sandboxing doc for distro commands).

Use WSL2 with bubblewrap and socat installed. WSL1 is not supported.

Sandbox modes (behavior)

From Sandboxing:

Auto-allow: sandboxed commands are auto-approved when they fit the sandbox. Commands that cannot be sandboxed (for example non-allowed network hosts) fall back to the normal permission flow. rm / rmdir targeting /, home, or other critical paths can still prompt.
Regular permissions: every Bash command goes through the normal permission flow even inside the sandbox.

Auto-allow is independent of acceptEdits: sandboxed Bash may run without prompting while file-edit tools still follow the active permission mode.

Common `sandbox` settings

These commonly used keys live under sandbox in settings.json (user, project, local, or managed). The live settings reference is authoritative and also covers advanced runtime paths, Apple Events, strict network allowlists/TLS termination, filesystem disabling, violation handling, and the full credentials group. Arrays merge across scopes unless a flag says otherwise.

Key	Purpose
`enabled`	Turn bash sandboxing on (macOS, Linux, WSL2). Default `false`.
`failIfUnavailable`	If `true`, exit at startup when the sandbox cannot start. If `false` (default), warn and run unsandboxed. For managed deployments that require a hard gate.
`autoAllowBashIfSandboxed`	Auto-approve bash when sandboxed. Default `true`.
`excludedCommands`	Patterns that always run outside the sandbox (example: `["docker *"]`). Use when a tool is incompatible with the sandbox.
`allowUnsandboxedCommands`	If `true` (default), Claude may retry with `dangerouslyDisableSandbox` after a failure (goes through permissions). If `false`, that escape hatch is disabled; everything must be sandboxed or listed in `excludedCommands`.
`filesystem.allowWrite`	Extra write paths for subprocesses (merged with `Edit(...)` allows).
`filesystem.denyWrite`	Block writes for subprocesses (merged with `Edit(...)` denies).
`filesystem.denyRead`	Block reads for subprocesses (merged with `Read(...)` denies).
`filesystem.allowRead`	Re-allow reads inside a denied region; wins over `denyRead`.
`filesystem.allowManagedReadPathsOnly`	Managed only: only managed `allowRead` entries apply; `denyRead` still merges from all sources. Default `false`.
`network.allowUnixSockets`	macOS: explicit Unix socket paths allowed in the sandbox. Ignored on Linux/WSL2.
`network.allowAllUnixSockets`	Linux/WSL2: allow all Unix sockets (broad; often needed because seccomp cannot filter by path). Default `false`.
`network.allowLocalBinding`	macOS: allow binding localhost ports. Default `false`.
`network.allowMachLookup`	macOS: extra XPC/Mach service names (trailing `*` allowed). For Simulator, Playwright, etc.
`network.allowedDomains`	Outbound allow list (wildcards such as `*.example.com`).
`network.deniedDomains`	Outbound deny list; wins when both match.
`network.allowManagedDomainsOnly`	Managed only: only managed `allowedDomains` and managed `WebFetch` allows count; others ignored; non-allowed domains blocked without prompting. Default `false`.
`network.httpProxyPort`	Bring-your-own HTTP proxy port (optional).
`network.socksProxyPort`	Bring-your-own SOCKS proxy port (optional).
`enableWeakerNestedSandbox`	Linux/WSL2: weaker sandbox for unprivileged Docker; reduces isolation. Default `false`.
`enableWeakerNetworkIsolation`	macOS: allow `trustd` for TLS when using `httpProxyPort` with MITM/custom CA; weakens network isolation. Default `false`.

Path prefixes (`filesystem.*`)

Prefix	Meaning
`/`	Absolute from filesystem root
`~/`	Under your home directory
`./` or no prefix	Project root for project settings, or `~/.claude` for user settings

Sandbox path rules differ from Read / Edit permission rule path syntax; see the settings doc.

Example configuration

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "allowUnsandboxedCommands": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

Unix sockets and Docker

Allowing /var/run/docker.sock effectively grants host-level access via the Docker API. Only allow sockets you truly need, per the Sandboxing security notes.

How sandboxing fits secure execution

Permissions gate which tools run. Sandbox constrains what Bash can touch on disk and network after a command is approved.
Combine with permissions.deny on .env and other secrets so Read tools cannot leak them even when Bash is boxed.
Auto mode still routes risky actions through its classifier; sandbox network requests are not implicitly trusted.

Example prompt

When a sandboxed command fails, paste the error and terminal context:

This npm script failed inside the sandbox. From the error, recommend the smallest settings.json change: excludedCommands, allowUnsandboxedCommands, or network.allowedDomains. Explain the security tradeoff in two sentences.

@terminal:npm

Sandbox mode

Prerequisites

Sandbox modes (behavior)

Common `sandbox` settings

Path prefixes (`filesystem.*`)

Example configuration

How sandboxing fits secure execution

Example prompt

See also

Auto mode

Permission denials

Codex approvals and sandbox

Security

@anthropic-ai/sandbox-runtime

On this page