Configure the sandboxed Bash tool changedsandboxing
Nearest release: v2.1.318, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 4 Nov 2026 00:34 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 4 Nov 2026 00:37 UTC.
Upstream edited
Recorded here
Lines+60added
Lines−28removed
From line
67
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits60to this page, all time
#### Add an AppArmor profile for bubblewrap ### Ubuntu's AppArmor restriction stops bubblewrap ### Sandboxed commands fail with `bwrap: setting up uid map: Permission denied`
The whole hunk
from line 67, old and new numbered
/
from line 67
6767* **Overrides**: choose whether commands that fail under the sandbox can fall back to running unsandboxed. This is the [`allowUnsandboxedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-allowunsandboxedcommands) setting
6868* **Config**: view the resolved sandbox settings
6969
70If 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.
70If the panel shows only a Dependencies tab, the sandbox can't start yet. Fix what the tab reports as described in [Set up Linux and WSL2](#set-up-linux-and-wsl2), restart Claude Code, and run `/sandbox` again.
7171
7272**2. Choose a mode**
7373
from line 93
9393
9494> [!WARNING]
9595>
96> By default, if the sandbox can't start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. To make Claude Code exit at startup instead, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) to `true`. Managed deployments that require sandboxing as a security gate can use this setting.
96> By default, when the platform doesn't support the sandbox or the dependency check at startup fails, Claude Code runs commands without sandboxing. To make Claude Code exit at startup instead, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) to `true`. Managed deployments that require sandboxing as a security gate can use this setting.
9797
9898### Confirm commands run inside the sandbox
9999
from line 131
131131
132132Ripgrep 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.
133133
134When a required dependency is missing, the Dependencies tab is the only tab shown until you install it. When only the optional seccomp filter is missing, the Dependencies tab appears alongside the other tabs. The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
134* **Dependencies is the only tab**: the sandbox can't start. Install what the tab lists as missing, or if it reports Ubuntu's AppArmor restriction, [add an AppArmor profile for bubblewrap](#add-an-apparmor-profile-for-bubblewrap)
135* **Dependencies appears beside the other tabs**: the tab lists a missing optional item, such as the seccomp filter. The sandbox can start without it, so install it only if you want what it adds
135136
136> [accordion] Ubuntu 24.04 and later: allow bubblewrap to create user namespaces
137>
138> On Ubuntu 24.04 and later, the default AppArmor policy prevents bubblewrap from creating the user namespaces it needs for isolation.
139>
140> To check whether your environment enforces this restriction, including inside WSL2, run `sysctl kernel.apparmor_restrict_unprivileged_userns`. If the command returns `0`, skip this step. If it prints a `No such file or directory` error, the key doesn't exist and you can skip this step. If it returns `1`, add an AppArmor profile that grants `bwrap` this capability:
141>
142> ```bash theme={null}
143> sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
144> abi <abi/4.0>,
145> include <tunables/global>
146>
147> profile bwrap /usr/bin/bwrap flags=(unconfined) {
148> userns,
149> include if exists <local/bwrap>
150> }
151> EOF
152> ```
153>
154> The profile applies only to `bwrap` itself, not to the commands it runs inside the sandbox. Reload AppArmor to apply it:
155>
156> ```bash theme={null}
157> sudo systemctl reload apparmor
158> ```
137The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
159138
160139> [accordion] WSL2 notes
161140>
from line 142
163142>
164143> On WSL2, WSL hands a launch of a Windows binary such as `cmd.exe`, `powershell.exe`, or anything under `/mnt/c/` to the Windows host over a Unix socket, so whether a sandboxed command can launch one follows the sandbox's [Unix-socket settings](https://code.claude.com/docs/en/settings-reference.md#sandbox-network-allowunixsockets): the optional seccomp filter has to be installed to block the socket in the first place. To allow these launches, set `allowAllUnixSockets`, which opens every Unix socket to sandboxed commands.
165144
145#### Add an AppArmor profile for bubblewrap
146
147Add the profile if Claude Code runs `/usr/bin/bwrap` and either of these happens:
148
149* Claude Code [reports Ubuntu's AppArmor restriction on user namespaces](#apparmor-restriction-stops-bubblewrap)
150* Sandboxed commands fail with `bwrap: setting up uid map: Permission denied` or `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` while [that restriction is on](#bwrap-uid-map-permission-denied)
151
152Claude Code runs the first `bwrap` on `PATH`, unless managed settings name one in [`sandbox.bwrapPath`](https://code.claude.com/docs/en/settings-reference#sandbox-bwrappath). To see which `bwrap` is first, run `which bwrap` in the shell you start Claude Code from. If Claude Code runs any path other than `/usr/bin/bwrap`, [lift the restriction with `sysctl`](#apparmor-restriction-stops-bubblewrap) instead.
153
154To add the profile for `/usr/bin/bwrap`, run this command:
155
156```bash theme={null}
157sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
158abi <abi/4.0>,
159include <tunables/global>
160
161profile bwrap /usr/bin/bwrap flags=(unconfined) {
162 userns,
163 include if exists <local/bwrap>
164}
165EOF
166```
167
168Reload AppArmor to apply it:
169
170```bash theme={null}
171sudo systemctl reload apparmor
172```
173
174Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox).
175
166176### Sandbox modes
167177
168178Claude Code offers two sandbox modes. In both, the sandbox enforces the same filesystem and network restrictions; the difference is only in whether sandboxed commands are auto-approved or require explicit permission.
from line 722
712722
713723The two keys beyond `enabled` control what happens when the sandbox cannot run a command:
714724
715* **`failIfUnavailable`**: a missing dependency such as bubblewrap on Linux blocks Claude Code from starting rather than falling back to unsandboxed execution
725* **`failIfUnavailable`**: when the platform doesn't support the sandbox or the dependency check at startup fails, Claude Code refuses to start rather than falling back to unsandboxed execution
716726* **`allowUnsandboxedCommands: false`**: Claude Code ignores the `dangerouslyDisableSandbox` escape hatch, so when a command fails under the sandbox, Claude can't retry it unsandboxed
717727
718728Consider these additions alongside them:
from line 907
897907### Bubblewrap fails to start inside a container
898908
899909In an unprivileged container, [bubblewrap](#os-level-enforcement) can't mount a fresh `/proc` filesystem, so sandboxed commands fail with a `bwrap` error such as `Can't mount proc on /newroot/proc: Operation not permitted`. Set [`enableWeakerNestedSandbox`](https://code.claude.com/docs/en/settings-reference#sandbox-enableweakernestedsandbox) to `true` so the 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 the setting exposes process information to sandboxed commands that a fresh `/proc` mount would hide.
910
911### Ubuntu's AppArmor restriction stops bubblewrap
912
913On Linux and WSL2, the message `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` means that Ubuntu's AppArmor restriction keeps the sandbox from starting.
914
915To get the sandbox to start, lift the restriction in one of these two ways:
916
917* [Add an AppArmor profile for bubblewrap](#add-an-apparmor-profile-for-bubblewrap) if Claude Code runs `/usr/bin/bwrap`
918* In your shell, run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts the restriction for every program on the machine and lasts until you reboot
919
920Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox).
921
922Until you lift the restriction, commands run without the sandbox under the regular permission flow, or Claude Code refuses to start if [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) is `true`.
923
924### Sandboxed commands fail with `bwrap: setting up uid map: Permission denied`
925
926On Linux and WSL2, this error or `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` can mean that Ubuntu's AppArmor restriction on user namespaces is stopping bubblewrap. To check, run `sysctl kernel.apparmor_restrict_unprivileged_userns` in your shell:
927
928* `kernel.apparmor_restrict_unprivileged_userns = 1`: the restriction is on. [Add an AppArmor profile](#add-an-apparmor-profile-for-bubblewrap) if Claude Code runs `/usr/bin/bwrap`, or run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts it for every program until you reboot. Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox)
929* Any other output: the restriction isn't the cause. To report the failure, run [`/feedback`](https://code.claude.com/docs/en/commands#all-commands) at the Claude Code prompt
930
931Before v2.1.310, Claude Code didn't check for this restriction at startup, so `/sandbox` didn't report it.
900932
901933### 0-byte read-only files appear at `.claude` settings paths, and "Yes, and don't ask again" doesn't save
902934
No line in this hunk matches that.