2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Sandboxing5# Configure the sandboxed Bash tool
6 6
7> Learn how Claude Code's sandboxed bash tool provides filesystem and network isolation for safer, more autonomous agent execution.7> Learn how Claude Code's sandboxed Bash tool provides filesystem and network isolation for safer, more autonomous agent execution.
8 8
9## Overview9The Bash sandbox lets Claude run most shell commands without stopping to ask permission. Instead of approving each command, you define which files and network domains commands can touch, and the operating system enforces that boundary for every Bash command and its child processes.
10 10
11Claude Code features native sandboxing to provide a more secure environment for agent execution while reducing the need for constant permission prompts. Instead of asking permission for each bash command, sandboxing creates defined boundaries upfront where Claude Code can work more freely with reduced risk.11This page covers how to:
12 12
13The sandboxed bash tool uses OS-level primitives to enforce both filesystem and network isolation.13* [Enable the sandbox](#get-started) and choose how sandboxed commands are approved
14* [Configure](#configure-sandboxing) which paths and network domains commands can reach
15* [Combine sandboxing with permission rules and permission modes](#how-sandboxing-relates-to-permissions-and-permission-modes)
16* [Enforce sandboxing across an organization](#configure-the-sandbox-for-your-organization) with managed settings
14 17
15## Why sandboxing matters18<Note>
16 19 To compare other isolation approaches such as dev containers, custom containers, and virtual machines, see [Sandbox environments](/en/sandbox-environments). To reduce permission prompts for tools other than Bash, see [permission modes](/en/permission-modes).
17Traditional permission-based security requires constant user approval for bash commands. While this provides control, it can lead to:20</Note>
18
19* **Approval fatigue**: Repeatedly clicking "approve" can cause users to pay less attention to what they're approving
20* **Reduced productivity**: Constant interruptions slow down development workflows
21* **Limited autonomy**: Claude Code cannot work as efficiently when waiting for approvals
22
23Sandboxing addresses these challenges by:
24
251. **Defining clear boundaries**: Specify exactly which directories and network hosts Claude Code can access
262. **Reducing permission prompts**: Safe commands within the sandbox don't require approval
273. **Maintaining security**: Attempts to access resources outside the sandbox trigger immediate notifications
284. **Enabling autonomy**: Claude Code can run more independently within defined limits
29
30<Warning>
31 Effective sandboxing requires **both** filesystem and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files like SSH keys. Without filesystem isolation, a compromised agent could backdoor system resources to gain network access. When configuring sandboxing it is important to ensure that your configured settings do not create bypasses in these systems.
32</Warning>
33
34## How it works
35 21
36### Filesystem isolation22## Get started
37 23
38The sandboxed bash tool restricts file system access to specific directories:24The sandbox is built into Claude Code and runs on macOS, Linux, and WSL2. Native Windows is not supported. On Windows, run Claude Code inside a WSL2 distribution.
39 25
40* **Default writes behavior**: Read and write access to the current working directory and its subdirectories26On macOS, there is nothing to install: sandboxing uses the built-in Seatbelt framework. On Linux and WSL2, the sandbox relies on two packages, covered in [Set up Linux and WSL2](#set-up-linux-and-wsl2). Even if you haven't installed them yet, you can start with `/sandbox`, because its panel shows whether anything is missing.
41* **Default read behavior**: Read access to the entire computer, except certain denied directories
42* **Blocked access**: Cannot modify files outside the current working directory without explicit permission
43* **Configurable**: Define custom allowed and denied paths through settings
44 27
45You can grant write access to additional paths using `sandbox.filesystem.allowWrite` in your settings. These restrictions are enforced at the OS level (Seatbelt on macOS, bubblewrap on Linux), so they apply to all subprocess commands, including tools like `kubectl`, `terraform`, and `npm`, not just Claude's file tools.28<Steps>
29 <Step title="Run /sandbox">
30 Start a Claude Code session and run the `/sandbox` command:
46 31
47### Network isolation32 ```text theme={null}
33 /sandbox
34 ```
48 35
49Network access is controlled through a proxy server running outside the sandbox:36 This opens the sandbox panel with three tabs:
50 37
51* **Domain restrictions**: Only approved domains can be accessed38 * **Mode**: choose how sandboxed commands are approved, covered in the next step
52* **User confirmation**: New domain requests trigger permission prompts (unless [`allowManagedDomainsOnly`](/en/settings#sandbox-settings) is enabled, which blocks non-allowed domains automatically)39 * **Overrides**: choose whether commands that fail under the sandbox can fall back to running unsandboxed. This is the [`allowUnsandboxedCommands`](/en/settings#sandbox-settings) setting
53* **Custom proxy support**: Advanced users can implement custom rules on outgoing traffic40 * **Config**: view the resolved sandbox settings
54* **Comprehensive coverage**: Restrictions apply to all scripts, programs, and subprocesses spawned by commands
55 41
56<Note>42 If the panel shows only a Dependencies tab, a required package is missing. Install it as described in [Set up Linux and WSL2](#set-up-linux-and-wsl2), restart Claude Code, and run `/sandbox` again.
57 The built-in proxy enforces the allowlist based on the requested hostname and does not terminate or inspect TLS traffic. See [Security limitations](#security-limitations) for the implications of this design, and [Custom proxy configuration](#custom-proxy-configuration) if your threat model requires TLS inspection.43 </Step>
58</Note>
59 44
60### OS-level enforcement45 <Step title="Choose a mode">
46 On the Mode tab, select auto-allow or regular permissions. Auto-allow runs sandboxed commands without prompting, and regular permissions keeps the regular permission prompts even when commands are sandboxed. See [Sandbox modes](#sandbox-modes) for which commands still prompt in auto-allow mode.
47 </Step>
61 48
62The sandboxed bash tool leverages operating system security primitives:49 <Step title="Run a Bash command">
50 Ask Claude to run a command, such as a build or a test suite. By default, commands inside the sandbox can write only to the working directory. The first time a command needs a new network domain, Claude Code prompts for approval.
63 51
64* **macOS**: Uses Seatbelt for sandbox enforcement52 Commands that cannot run sandboxed fall back to the regular permission flow. To widen or narrow these boundaries, see [Configure sandboxing](#configure-sandboxing).
65* **Linux**: Uses [bubblewrap](https://github.com/containers/bubblewrap) for isolation53 </Step>
66* **WSL2**: Uses bubblewrap, same as Linux54</Steps>
67 55
68WSL1 is not supported because bubblewrap requires kernel features only available in WSL2.56Selecting a mode in the panel writes to your project's local settings at `.claude/settings.local.json`, which apply to the current project and are not checked into git. To enable the sandbox across all of your projects, set [`sandbox.enabled`](/en/settings#sandbox-settings) to `true` in your user settings at `~/.claude/settings.json`. To enforce sandboxing for every developer in an organization, use [managed settings](#enforce-sandboxing-with-managed-settings).
69 57
70These OS-level restrictions ensure that all child processes spawned by Claude Code's commands inherit the same security boundaries.58<Warning>
59 By default, if the sandbox cannot start because dependencies are missing or the platform is unsupported, Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.
60</Warning>
71 61
72## Getting started62### Set up Linux and WSL2
73 63
74### Prerequisites64On Linux and WSL2, the sandbox relies on two packages:
75 65
76On **macOS**, sandboxing works out of the box using the built-in Seatbelt framework.66* [`bubblewrap`](https://github.com/containers/bubblewrap): the unprivileged sandboxing tool that enforces filesystem isolation
67* [`socat`](http://www.dest-unreach.org/socat/): the relay used to route network traffic through the sandbox proxy
77 68
78On **Linux and WSL2**, install the required packages first:69Install them with your distribution's package manager:
79 70
80<Tabs>71<Tabs>
81 <Tab title="Ubuntu/Debian">72 <Tab title="Ubuntu/Debian">
91 </Tab>82 </Tab>
92</Tabs>83</Tabs>
93 84
94On Ubuntu 24.04 and later, the default AppArmor policy prevents bubblewrap from creating the user namespaces it needs for isolation. Add an AppArmor profile that grants `bwrap` this capability:85After installing, the Dependencies tab in `/sandbox` shows whether `ripgrep`, `bubblewrap`, `socat`, and the seccomp filter are available on your platform. Ripgrep is bundled with the native Claude Code binary. The seccomp filter is optional and adds Unix domain socket blocking. Install it with `npm install -g @anthropic-ai/sandbox-runtime` if it is missing.
95
96```bash theme={null}
97sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
98abi <abi/4.0>,
99include <tunables/global>
100 86
101profile bwrap /usr/bin/bwrap flags=(unconfined) {87When a required dependency is missing, the Dependencies tab is the only tab shown until you install it. The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
102 userns,
103 include if exists <local/bwrap>
104}
105EOF
106```
107
108The profile applies only to `bwrap` itself, not to the commands it runs inside the sandbox. Reload AppArmor to apply it:
109 88
110```bash theme={null}89<AccordionGroup>
111sudo systemctl reload apparmor90 <Accordion title="Ubuntu 24.04 and later: allow bubblewrap to create user namespaces">
112```91 On Ubuntu 24.04 and later, the default AppArmor policy prevents bubblewrap from creating the user namespaces it needs for isolation.
113 92
114WSL1 does not support sandboxing because it lacks the required Linux namespace primitives. If you see `Sandboxing requires WSL2`, upgrade your distribution to WSL2 or run Claude Code without sandboxing.93 To check whether your environment enforces this restriction, including inside WSL2, run `sysctl kernel.apparmor_restrict_unprivileged_userns`. If the key does not exist or returns `0`, skip this step. If it returns `1`, add an AppArmor profile that grants `bwrap` this capability:
115 94
116On WSL2, sandboxed commands cannot launch Windows binaries such as `cmd.exe`, `powershell.exe`, or anything under `/mnt/c/`. WSL hands these off to the Windows host over a Unix socket, which the sandbox blocks. If a command needs to invoke a Windows binary, add it to [`excludedCommands`](/en/settings#sandbox-settings) so it runs outside the sandbox.95 ```bash theme={null}
96 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
97 abi <abi/4.0>,
98 include <tunables/global>
117 99
118### Enable sandboxing100 profile bwrap /usr/bin/bwrap flags=(unconfined) {
101 userns,
102 include if exists <local/bwrap>
103 }
104 EOF
105 ```
119 106
120You can enable sandboxing by running the `/sandbox` command:107 The profile applies only to `bwrap` itself, not to the commands it runs inside the sandbox. Reload AppArmor to apply it:
121 108
122```text theme={null}109 ```bash theme={null}
123/sandbox110 sudo systemctl reload apparmor
124```111 ```
112 </Accordion>
125 113
126This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.114 <Accordion title="WSL2 notes">
115 Check your WSL version with `wsl -l -v` from PowerShell. If you see `Sandboxing requires WSL2`, your distribution is running WSL1. Upgrade it to WSL2 or run Claude Code without sandboxing.
127 116
128By default, if the sandbox cannot start (missing dependencies or unsupported platform), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.117 On WSL2, sandboxed commands cannot launch Windows binaries such as `cmd.exe`, `powershell.exe`, or anything under `/mnt/c/`. WSL hands these off to the Windows host over a Unix socket, which the sandbox blocks. If a command needs to invoke a Windows binary, add it to [`excludedCommands`](/en/settings#sandbox-settings) so it runs outside the sandbox.
118 </Accordion>
119</AccordionGroup>
129 120
130### Sandbox modes121### Sandbox modes
131 122
132Claude Code offers two sandbox modes:123Claude Code offers two sandbox modes:
133 124
134**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit deny rules are always respected, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a permission prompt. Ask rules apply only to commands that fall back to the regular permission flow.125**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed, such as those needing network access to non-allowed hosts, fall back to the regular permission flow, where Claude Code checks your [permission rules](/en/permissions) and prompts you for any command those rules do not already allow.
126
127Even in auto-allow mode, the following still apply:
128
129* Explicit [deny rules](/en/permissions) are always respected
130* `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a permission prompt
131* [Ask rules](/en/permissions) apply to commands that fall back to the regular permission flow
135 132
136**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.133**Regular permissions mode**: All Bash commands go through the regular permission flow, even when sandboxed. This provides more control but requires more approvals.
137 134
138In both modes, the sandbox enforces the same filesystem and network restrictions. The difference is only in whether sandboxed commands are auto-approved or require explicit permission.135In both modes, the sandbox enforces the same filesystem and network restrictions. The difference is only in whether sandboxed commands are auto-approved or require explicit permission.
139 136
137Some commands cannot run inside the sandbox at all, such as tools that are incompatible with it or that need a host you have not allowed. Rather than failing the task or requiring you to turn sandboxing off, Claude Code includes an escape hatch: when a command fails because of sandbox restrictions, Claude analyzes the failure and may retry the command with the `dangerouslyDisableSandbox` parameter. The retried command runs outside the sandbox, so it goes through the regular permission flow and requires your approval.
138
139You can disable this escape hatch by setting `"allowUnsandboxedCommands": false` in your [sandbox settings](/en/settings#sandbox-settings). When disabled, which the `/sandbox` Overrides tab shows as **Strict sandbox mode**, the `dangerouslyDisableSandbox` parameter is completely ignored and all commands must run sandboxed or be explicitly listed in `excludedCommands`.
140
140<Info>141<Info>
141 Auto-allow mode works independently of your permission mode setting. Even if you're not in "accept edits" mode, sandboxed bash commands will run automatically when auto-allow is enabled. This means bash commands that modify files within the sandbox boundaries will execute without prompting, even when file edit tools would normally require approval.142 Auto-allow mode works independently of your permission mode setting. Even if you're not in "accept edits" mode, sandboxed Bash commands will run automatically when auto-allow is enabled. This means Bash commands that modify files within the sandbox boundaries will execute without prompting, even when file edit tools would normally require approval.
142</Info>143</Info>
143 144
144### Configure sandboxing145## Configure sandboxing
145
146Customize sandbox behavior through your `settings.json` file. See [Settings](/en/settings#sandbox-settings) for complete configuration reference.
147 146
148#### Granting subprocess write access to specific paths147Customize sandbox behavior through your `settings.json` file. See [Settings](/en/settings#sandbox-settings) for the complete configuration reference.
149 148
150By default, sandboxed commands can only write to the current working directory. If subprocess commands like `kubectl`, `terraform`, or `npm` need to write outside the project directory, use `sandbox.filesystem.allowWrite` to grant access to specific paths:149By default, sandboxed commands can only write to the current working directory. If subprocess commands like `kubectl`, `terraform`, or `npm` need to write outside the project directory, use `sandbox.filesystem.allowWrite` to grant access to specific paths:
151 150
162 161
163These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with `excludedCommands`.162These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with `excludedCommands`.
164 163
165When `allowWrite` (or `denyWrite`/`denyRead`/`allowRead`) is defined in multiple [settings scopes](/en/settings#settings-precedence), the arrays are **merged**, meaning paths from every scope are combined, not replaced. For example, if managed settings allow writes to `/opt/company-tools` and a user adds `~/.kube` in their personal settings, both paths are included in the final sandbox configuration. This means users and projects can extend the list without duplicating or overriding paths set by higher-priority scopes.164When the same filesystem array is defined in multiple [settings scopes](/en/settings#settings-precedence), the arrays are merged: paths from every scope are combined, not replaced.
166 165
167Path prefixes control how paths are resolved:166Path prefixes control how paths are resolved:
168 167
172| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |171| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |
173| `./` or no prefix | Relative to the project root for project settings, or to `~/.claude` for user settings | `./output` in `.claude/settings.json` resolves to `<project-root>/output` |172| `./` or no prefix | Relative to the project root for project settings, or to `~/.claude` for user settings | `./output` in `.claude/settings.json` resolves to `<project-root>/output` |
174 173
175The older `//path` prefix for absolute paths still works. If you previously used single-slash `/path` expecting project-relative resolution, switch to `./path`. This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is an absolute path.174This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is absolute.
176 175
177You can also deny write or read access using `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead`. These are merged with any paths from `Edit(...)` and `Read(...)` permission rules. To re-allow reading specific paths within a denied region, use `sandbox.filesystem.allowRead`, which takes precedence over `denyRead`. When `allowManagedReadPathsOnly` is enabled in managed settings, only managed `allowRead` entries are respected; user, project, and local `allowRead` entries are ignored. `denyRead` still merges from all sources.176You can also deny write or read access using `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead`, and re-allow specific paths within a denied region using `sandbox.filesystem.allowRead`.
178 177
179For example, to block reading from the entire home directory while still allowing reads from the current project, add this to your project's `.claude/settings.json`:178The example below blocks reading from the entire home directory while still allowing reads from the current project. Place it in your project's `.claude/settings.json`, because the relative path `.` resolves to the project root only when the configuration lives in project settings:
180 179
181```json theme={null}180```json theme={null}
182{181{
192 191
193The `.` in `allowRead` resolves to the project root because this configuration lives in project settings. If you placed the same configuration in `~/.claude/settings.json`, `.` would resolve to `~/.claude` instead, and project files would remain blocked by the `denyRead` rule.192The `.` in `allowRead` resolves to the project root because this configuration lives in project settings. If you placed the same configuration in `~/.claude/settings.json`, `.` would resolve to `~/.claude` instead, and project files would remain blocked by the `denyRead` rule.
194 193
195<Tip>194## How sandboxing works
196 Not all commands are compatible with sandboxing out of the box. Some notes that may help you make the most out of the sandbox:
197 195
198 * Many CLI tools require accessing certain hosts. As you use these tools, they will request permission to access certain hosts. Granting permission will allow them to access these hosts now and in the future, enabling them to safely execute inside the sandbox.196### Filesystem isolation
199 * `watchman` is incompatible with running in the sandbox. If you're running `jest`, consider using `jest --no-watchman`
200 * `docker` is incompatible with running in the sandbox. Consider specifying `docker *` in `excludedCommands` to force it to run outside of the sandbox.
201</Tip>
202 197
203<Note>198The sandboxed Bash tool restricts file system access to specific directories:
204 Claude Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions (such as network connectivity issues or incompatible tools), Claude is prompted to analyze the failure and may retry the command with the `dangerouslyDisableSandbox` parameter. Commands that use this parameter go through the normal Claude Code permissions flow requiring user permission to execute. This allows Claude Code to handle edge cases where certain tools or network operations cannot function within sandbox constraints.
205 199
206 You can disable this escape hatch by setting `"allowUnsandboxedCommands": false` in your [sandbox settings](/en/settings#sandbox-settings). When disabled, the `dangerouslyDisableSandbox` parameter is completely ignored and all commands must run sandboxed or be explicitly listed in `excludedCommands`.200* **Default write behavior**: read and write access to the current working directory and its subdirectories
201* **Default read behavior**: read access to the entire computer, except certain denied directories. Note that this default still allows reading credential files such as `~/.aws/credentials` and `~/.ssh/`. Add them to `denyRead` to block them.
202* **Blocked access**: cannot modify files outside the current working directory without explicit permission, including shell configuration files such as `~/.bashrc` and system binaries in `/bin/`
203* **Configurable**: define custom allowed and denied paths through settings
204
205You can grant write access to additional paths using `sandbox.filesystem.allowWrite` in your settings. These restrictions are enforced at the OS level, so they apply to all subprocess commands, including tools like `kubectl`, `terraform`, and `npm`, not just Claude's file tools.
206
207### Network isolation
208
209Network access is controlled through a proxy server running outside the sandbox:
210
211* **Domain restrictions**: no domains are pre-allowed. The first time a command needs a new domain, Claude Code prompts for approval. Pre-allow domains with [`allowedDomains`](/en/settings#sandbox-settings) to avoid the prompt.
212* **Managed lockdown**: if [`allowManagedDomainsOnly`](/en/settings#sandbox-settings) is set in managed settings, non-allowed domains are blocked automatically instead of prompting, and only `allowedDomains` from managed settings are honored.
213* **Custom proxy support**: advanced users can implement custom rules on outgoing traffic
214* **Comprehensive coverage**: restrictions apply to all scripts, programs, and subprocesses spawned by commands
215
216<Note>
217 The built-in proxy enforces the allowlist based on the requested hostname and does not terminate or inspect TLS traffic. See [Security limitations](#security-limitations) for the implications of this design, and [Custom proxy configuration](#custom-proxy-configuration) if your threat model requires TLS inspection.
207</Note>218</Note>
208 219
209## Security benefits220### OS-level enforcement
210 221
211### Protection against prompt injection222The sandboxed Bash tool leverages operating system security primitives:
212 223
213Even if an attacker successfully manipulates Claude Code's behavior through prompt injection, the sandbox ensures your system remains secure:224* **macOS**: uses Seatbelt for sandbox enforcement
225* **Linux**: uses [bubblewrap](https://github.com/containers/bubblewrap) for isolation
226* **WSL2**: uses bubblewrap, same as Linux
214 227
215**Filesystem protection:**228WSL1 is not supported because bubblewrap requires kernel features only available in WSL2. These OS-level restrictions ensure that all child processes spawned by Claude Code's commands inherit the same security boundaries.
216 229
217* Cannot modify critical config files such as `~/.bashrc`230These same primitives are available as the standalone [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) package, which the [Sandbox environments](/en/sandbox-environments#sandbox-runtime) page covers as a separate approach for wrapping the entire Claude Code process.
218* Cannot modify system-level files in `/bin/`
219* Cannot read files that are denied in your [Claude permission settings](/en/permissions#manage-permissions)
220 231
221**Network protection:**232## How sandboxing relates to permissions and permission modes
222 233
223* Cannot exfiltrate data to attacker-controlled servers234Sandboxing, [permission rules](/en/permissions), and [permission modes](/en/permission-modes) are complementary layers. The sections below cover how the sandbox interacts with each.
224* Cannot download malicious scripts from unauthorized domains
225* Cannot make unexpected API calls to unapproved services
226* Cannot contact any domains not explicitly allowed
227 235
228**Monitoring and control:**236### Permission rules
229 237
230* All access attempts outside the sandbox are blocked at the OS level238Permission rules and sandboxing control different things:
231* You receive immediate notifications when boundaries are tested
232* You can choose to deny, allow once, or permanently update your configuration
233 239
234### Reduced attack surface240* **Permission rules** control which tools Claude Code can use and are evaluated before any tool runs. They apply to all tools: Bash, Read, Edit, WebFetch, MCP, and others.
241* **Sandboxing** provides OS-level enforcement that restricts what Bash commands can access at the filesystem and network level. It applies only to Bash commands and their child processes.
235 242
236Sandboxing limits the potential damage from:243The two layers also differ in how they are enforced. Claude Code evaluates permission decisions before a command runs, based on the command string and, in auto mode, a separate classifier's judgment about whether the command is safe. The operating system enforces the sandbox boundary on the running process, so it holds regardless of what the model chose to run and even if an allowed command does more than its name suggests.
237 244
238* **Malicious dependencies**: NPM packages or other dependencies with harmful code245Filesystem and network restrictions are configured through both sandbox settings and permission rules:
239* **Compromised scripts**: Build scripts or tools with security vulnerabilities
240* **Social engineering**: Attacks that trick users into running dangerous commands
241* **Prompt injection**: Attacks that trick Claude into running dangerous commands
242 246
243### Transparent operation247| Setting or rule | What it does |
248| :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
249| `sandbox.filesystem.allowWrite` | Grants subprocess write access to paths outside the working directory |
250| `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead` | Block subprocess access to specific paths |
251| `sandbox.filesystem.allowRead` | Re-allows reading specific paths within a `denyRead` region |
252| `Edit` allow rules | Grant write access to specific paths, the same way `sandbox.filesystem.allowWrite` does |
253| `Read` and `Edit` deny rules | Block access to specific files or directories |
254| `WebFetch` allow and deny rules | Control domain access |
255| Sandbox `allowedDomains` | Controls which domains Bash commands can reach |
256| Sandbox `deniedDomains` | Blocks specific domains even when a broader `allowedDomains` wildcard would otherwise permit them |
244 257
245When Claude Code attempts to access network resources outside the sandbox:258Paths from both `sandbox.filesystem` settings and permission rules are merged together into the final sandbox configuration.
246 259
2471. The operation is blocked at the OS level260The [claude-code repository's examples directory](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios, including sandbox-specific examples. Use these as starting points and adjust them to fit your needs.
2482. You receive an immediate notification
2493. You can choose to:
250 * Deny the request
251 * Allow it once
252 * Update your sandbox configuration to permanently allow it
253 261
254## Security Limitations262### Permission modes
255 263
256* Network Sandboxing Limitations: The network filtering system operates by restricting the domains that processes are allowed to connect to. The built-in proxy does not terminate or perform TLS inspection on outbound traffic, so the contents of encrypted connections are not examined. You are responsible for ensuring that only trusted domains are allowed in your policy.264`/sandbox` is not a [permission mode](/en/permission-modes). Permission modes decide whether a tool call runs and whether you are prompted first, while the sandbox restricts what a Bash command can access once it runs. They differ in what they control and what replaces the per-action prompt:
257 265
258<Warning>266| | What it controls | What replaces the prompt |
259 Allowing broad domains such as `github.com` can create paths for data exfiltration. Because the proxy makes its allow decision from the client-supplied hostname without inspecting TLS, code running inside the sandbox can potentially use [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) or similar techniques to reach hosts outside the allowlist. If your threat model requires stronger guarantees, configure a [custom proxy](#custom-proxy-configuration) that terminates TLS and inspects traffic, and install its CA certificate inside the sandbox. Stronger TLS-aware network isolation is an active area of development.267| :----------------------------------------------------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
260</Warning>268| `/sandbox` | What a Bash command can access once it runs | The sandbox boundary itself, in [auto-allow mode](#sandbox-modes) |
269| [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) | Whether each tool call runs | A classifier that reviews actions |
270| `--dangerously-skip-permissions` | Whether each tool call runs | Nothing. [Protected path](/en/permission-modes#protected-paths) checks are also skipped; only removing `/` or your home directory still prompts |
261 271
262* Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `/var/run/docker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.272The sandbox's [auto-allow mode](#sandbox-modes) is separate from [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode): auto-allow approves Bash commands because the sandbox boundary contains them, while auto mode uses a classifier to review actions. The two work independently and can be combined. To choose an isolation boundary for unattended runs, see [Sandbox environments](/en/sandbox-environments#how-isolation-relates-to-permission-modes).
263* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.
264* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.
265 273
266## How sandboxing relates to permissions274## Configure the sandbox for your organization
267 275
268Sandboxing and [permissions](/en/permissions) are complementary security layers that work together:276Administrators can require sandboxing for every user, keep developers from widening the policy, and route sandbox traffic through a corporate proxy.
269 277
270* **Permissions** control which tools Claude Code can use and are evaluated before any tool runs. They apply to all tools: Bash, Read, Edit, WebFetch, MCP, and others.278### Enforce sandboxing with managed settings
271* **Sandboxing** provides OS-level enforcement that restricts what Bash commands can access at the filesystem and network level. It applies only to Bash commands and their child processes.
272 279
273Filesystem and network restrictions are configured through both sandbox settings and permission rules:280To require the sandbox for every developer, deliver the `sandbox` keys through [managed settings](/en/settings#settings-files), either as a file managed by your MDM or through [server-managed settings](/en/server-managed-settings) on Claude.ai.
274 281
275* Use `sandbox.filesystem.allowWrite` to grant subprocess write access to paths outside the working directory282The following managed settings configuration enables the sandbox, refuses to start Claude Code if the sandbox cannot initialize, and prevents the model from retrying commands outside the sandbox:
276* Use `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead` to block subprocess access to specific paths
277* Use `sandbox.filesystem.allowRead` to re-allow reading specific paths within a `denyRead` region
278* Use `Read` and `Edit` deny rules to block access to specific files or directories
279* Use `WebFetch` allow/deny rules to control domain access
280* Use sandbox `allowedDomains` to control which domains Bash commands can reach
281* Use sandbox `deniedDomains` to block specific domains even when a broader `allowedDomains` wildcard would otherwise permit them
282 283
283Paths from both `sandbox.filesystem` settings and permission rules are merged together into the final sandbox configuration.284```json theme={null}
285{
286 "sandbox": {
287 "enabled": true,
288 "failIfUnavailable": true,
289 "allowUnsandboxedCommands": false
290 }
291}
292```
293
294The two keys beyond `enabled` control what happens when the sandbox cannot run a command:
295
296* **`failIfUnavailable`**: a missing dependency such as bubblewrap on Linux blocks Claude Code from starting rather than showing a warning and falling back to unsandboxed execution
297* **`allowUnsandboxedCommands: false`**: the `dangerouslyDisableSandbox` escape hatch is ignored, so commands that fail under the sandbox cannot be retried outside it
298
299Two additions are worth considering alongside them. Add `excludedCommands` for any organization-approved tools that must run without isolation. Add [`denyRead`](#filesystem-isolation) entries for credential directories such as `~/.aws` and `~/.ssh`, which the default read policy still allows.
300
301The sandbox does not run on native Windows, so if your fleet includes Windows hosts, scope this configuration to macOS and Linux or have those users run Claude Code inside WSL2 or a container.
302
303### Keep developers from widening the policy
304
305For boolean keys such as `enabled` and `failIfUnavailable`, Claude Code uses the managed value and ignores anything a developer sets locally. For array keys such as `excludedCommands` and `allowRead`, Claude Code merges entries from every scope, so a developer can append entries that widen the policy.
284 306
285This [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios, including sandbox-specific examples. Use these as starting points and adjust them to fit your needs.307Set `allowManagedReadPathsOnly` to `true` in managed settings so that only `allowRead` entries from managed settings are honored. User, project, and local `allowRead` entries are ignored. This prevents developers from widening read access beyond the organization-approved paths. To lock network domains to the managed values the same way, set [`allowManagedDomainsOnly`](/en/settings#sandbox-settings).
286 308
287## Advanced usage309`excludedCommands` has no equivalent managed-only lockdown, so a developer can always append entries that run additional commands outside the sandbox. Keep the managed list narrow.
288 310
289### Custom proxy configuration311### Custom proxy configuration
290 312
295* Log all network requests317* Log all network requests
296* Integrate with existing security infrastructure318* Integrate with existing security infrastructure
297 319
320To point Claude Code at your proxy, set the proxy ports in [sandbox settings](/en/settings#sandbox-settings):
321
298```json theme={null}322```json theme={null}
299{323{
300 "sandbox": {324 "sandbox": {
306}330}
307```331```
308 332
309### Integration with existing security tools333## Troubleshooting
310 334
311The sandboxed bash tool works alongside:335Some commands fail inside the sandbox even though they work outside it. The fixes below cover the most common cases.
312 336
313* **Permission rules**: Combine with [permission settings](/en/permissions) for defense-in-depth337* **Commands fail with a host-not-allowed error**: many CLI tools need to reach specific hosts. Granting permission when prompted adds the host to your allowed list so the tool runs inside the sandbox in future.
314* **Development containers**: Use with [dev containers](/en/devcontainer) for additional isolation338* **`jest` hangs or fails**: `watchman` is incompatible with the sandbox. Run `jest --no-watchman` instead.
315* **Enterprise policies**: Enforce sandbox configurations through [managed settings](/en/settings#settings-precedence)339* **Go-based CLIs fail TLS verification on macOS**: tools such as `gh`, `gcloud`, and `terraform` may fail TLS verification under Seatbelt. List these tools in `excludedCommands` to run them outside the sandbox. If you are using `httpProxyPort` with a MITM proxy and custom CA, set [`enableWeakerNetworkIsolation`](/en/settings#sandbox-settings) to `true` instead.
340* **`docker` commands fail**: `docker` is incompatible with the sandbox. Add `docker *` to `excludedCommands` to run it outside the sandbox.
341* **Bubblewrap fails to start inside a container**: in an unprivileged container, bubblewrap cannot mount a fresh `/proc` filesystem. Set [`enableWeakerNestedSandbox`](/en/settings#sandbox-settings) to `true` so the inner sandbox bind-mounts the container's existing `/proc` instead. Only use this setting when the outer container already provides the isolation boundary you need, since it exposes process information to sandboxed commands that a fresh `/proc` mount would hide.
342* **Seccomp filter on Linux**: the seccomp filter is required to block Unix domain sockets. The Dependencies tab in `/sandbox` shows whether it is available. If it is missing, run `npm install -g @anthropic-ai/sandbox-runtime` to install the helper.
343* **`--dangerously-skip-permissions` fails as root**: this flag is blocked when running as root or via sudo on Linux and macOS, because root access combined with no permission prompts can modify any file or service on the system. The check is skipped automatically inside a recognized sandbox. To run autonomously in a container, use the [dev container](/en/devcontainer) configuration, which runs Claude Code as a non-root user.
316 344
317## Best practices345## Limitations
318 346
3191. **Start restrictive**: Begin with minimal permissions and expand as needed347Sandboxing reduces risk but is not a complete isolation boundary. Review the limitations below before relying on it as a hard security control.
3202. **Monitor logs**: Review sandbox violation attempts to understand Claude Code's needs
3213. **Use environment-specific configs**: Different sandbox rules for development vs. production contexts
3224. **Combine with permissions**: Use sandboxing alongside IAM policies for comprehensive security
3235. **Test configurations**: Verify your sandbox settings don't block legitimate workflows
324 348
325## Open source349### Security limitations
326 350
327The sandbox runtime is available as an open source npm package for use in your own agent projects. This enables the broader AI agent community to build safer, more secure autonomous systems. This can also be used to sandbox other programs you may wish to run. For example, to sandbox an MCP server you could run:351* **Network filtering**: the network filtering system operates by restricting the domains that processes are allowed to connect to. The built-in proxy does not terminate or perform TLS inspection on outbound traffic, so the contents of encrypted connections are not examined. You are responsible for ensuring that only trusted domains are allowed in your policy.
328 352
329```bash theme={null}353<Warning>
330npx @anthropic-ai/sandbox-runtime <command-to-sandbox>354 Allowing broad domains such as `github.com` can create paths for data exfiltration. Because the proxy makes its allow decision from the client-supplied hostname without inspecting TLS, code running inside the sandbox can potentially use [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) or similar techniques to reach hosts outside the allowlist. If your threat model requires stronger guarantees, configure a [custom proxy](#custom-proxy-configuration) that terminates TLS and inspects traffic, and install its CA certificate inside the sandbox. Stronger TLS-aware network isolation is an active area of development.
331```355</Warning>
332 356
333For implementation details and source code, visit the [GitHub repository](https://github.com/anthropic-experimental/sandbox-runtime).357* **Privilege escalation via Unix sockets**: the `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, allowing access to `/var/run/docker.sock` effectively grants access to the host system through the Docker socket. Consider carefully any Unix sockets that you allow through the sandbox.
358* **Filesystem permission escalation**: overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files such as `.bashrc` or `.zshrc` can lead to code execution in different security contexts when other users or system processes access these files.
359* **Linux sandbox strength**: the Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside Docker environments without privileged namespaces, or on Linux hosts where unprivileged user namespaces are disabled by sysctl. This option considerably weakens security and should only be used when additional isolation is otherwise enforced.
360* **Settings files protected**: the sandbox automatically denies write access to Claude Code's `settings.json` files at every scope and to the managed settings directory, so a sandboxed command cannot modify its own policy.
334 361
335## Limitations362### Platform and tool compatibility
336 363
337* **Performance overhead**: Minimal, but some filesystem operations may be slightly slower364* **Platform support**: supports macOS, Linux, and WSL2. WSL1 and native Windows are not supported.
338* **Compatibility**: Some tools that require specific system access patterns may need configuration adjustments, or may even need to be run outside of the sandbox365* **Performance overhead**: minimal, but some filesystem operations may be slightly slower.
339* **Platform support**: Supports macOS, Linux, and WSL2. WSL1 is not supported. Native Windows support is planned.366* **Tool compatibility**: some tools that require specific system access patterns may need configuration adjustments, or may need to be run outside the sandbox.
340 367
341## What sandboxing does not cover368### Scope
342 369
343The sandbox isolates Bash subprocesses. Other tools operate under different boundaries:370The sandbox isolates Bash subprocesses. Other tools operate under different boundaries:
344 371
345* **Built-in file tools**: Read, Edit, and Write use the permission system directly rather than running through the sandbox. See [permissions](/en/permissions).372* **Built-in file tools**: Read, Edit, and Write use the permission system directly rather than running through the sandbox. See [permissions](/en/permissions).
346* **Computer use**: when Claude opens apps and controls your screen, it runs on your actual desktop rather than in an isolated environment. Per-app permission prompts gate each application. See [computer use in the CLI](/en/computer-use) or [computer use in Desktop](/en/desktop#let-claude-use-your-computer).373* **Computer use**: when Claude opens apps and controls your screen, it runs on your actual desktop rather than in an isolated environment. Per-app permission prompts gate each application. See [computer use in the CLI](/en/computer-use) or [computer use in Desktop](/en/desktop#let-claude-use-your-computer).
374* **Environment variables**: sandboxed Bash commands inherit the parent process environment by default, including any credentials set there. To strip Anthropic and cloud provider credentials from subprocesses, set [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/en/env-vars).
375* **Subagents**: [subagents](/en/sub-agents) run in the same process as the parent session and use the same sandbox configuration. Bash commands inside a subagent are sandboxed when sandboxing is enabled in the parent session.
376
377<Warning>
378 Effective sandboxing requires both filesystem and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files like SSH keys. Without filesystem isolation, a compromised agent could backdoor system resources to gain network access. When you widen the defaults, check that an `allowWrite` path, a broad `allowedDomains` entry, or an `excludedCommands` exception does not undo a restriction on the other side.
379</Warning>
347 380
348## See also381## See also
349 382
350* [Security](/en/security) - Comprehensive security features and best practices383* [Sandbox environments](/en/sandbox-environments): compare the built-in sandbox with dev containers, containers, and VMs
351* [Permissions](/en/permissions) - Permission configuration and access control384* [Security](/en/security): comprehensive security features and best practices
352* [Settings](/en/settings) - Complete configuration reference385* [Permissions](/en/permissions): permission configuration and access control
353* [CLI reference](/en/cli-reference) - Command-line options386* [Settings](/en/settings): complete configuration reference
387* [CLI reference](/en/cli-reference): command-line options
