Configure the sandboxed Bash tool changedsandboxing
Upstream edited this page at 25 Oct 2026 14:22 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 25 Oct 2026 14:37 UTC.
Upstream edited
Recorded here
Lines+27added
Lines−3removed
From line
219
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits56to this page, all time
### Commands are refused with `Sandbox is required`
The whole hunk
from line 219, old and new numbered
/
from line 219
219219* **An ask rule for the parameter**: add an [ask rule](https://code.claude.com/docs/en/permissions.md#match-by-input-parameter) for `Bash(dangerouslyDisableSandbox:true)` to be prompted on Bash retries. You get the prompt in auto mode and `bypassPermissions` mode too, and the rule takes precedence over a matching allow rule
220220* **[`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) covers the retries that prompt while it's on
221221
222While commands are refused with a [`Sandbox is required` message](#commands-refused-with-sandbox-is-required), Claude Code ignores the `dangerouslyDisableSandbox` parameter and refuses the retry too.
223
222224#### Turn off the retry with strict sandbox mode
223225
224226You can disable the unsandboxed retry by setting `"allowUnsandboxedCommands": false` in your [sandbox settings](https://code.claude.com/docs/en/settings-reference.md#sandbox-settings). With the retry disabled, Claude Code ignores the `dangerouslyDisableSandbox` parameter. While the sandbox is running, commands Claude runs are then sandboxed unless they match an `excludedCommands` entry. To keep Claude Code from running commands unsandboxed when the sandbox can't start, also set [`failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable). The `/sandbox` **Overrides** tab shows this setting as **Strict sandbox mode**.
from line 897
895897
896898### 0-byte read-only files appear at `.claude` settings paths, and "Yes, and don't ask again" doesn't save
897899
898On Linux and WSL2, the sandbox holds a write denial on a file that doesn't exist yet by creating a 0-byte read-only placeholder there while a sandboxed command runs. The sandbox removes the placeholder afterward. If a session is killed before that cleanup runs, for example by SIGKILL, the placeholders stay behind. Later sessions bind the placeholders read-only again on every start, so a settings write such as saving a permission choice fails at a path where a placeholder remains.
900On Linux and WSL2, the sandbox holds a write denial on a file that doesn't exist yet by creating a 0-byte read-only placeholder there while a sandboxed command runs. The sandbox removes the placeholder afterward.
899901
900Run `claude doctor` in your terminal to list the leftover placeholder files. The [`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/en/errors#stale-sandbox-mask-files-left-by-a-killed-session) warning names some of them and counts the rest. Delete each file with `rm` while no other Claude Code session is running in that project. Before v2.1.257, Claude Code left the same placeholders behind without flagging them.
902A placeholder stays behind in cases such as these:
901903
904* The session is killed before that cleanup runs, for example by SIGKILL
905* The session exits while a sandboxed command is still running, such as a background command
906
907Later sessions bind the placeholders read-only again on every start, so a settings write such as saving a permission choice fails at a path where a placeholder remains.
908
909Run `claude doctor` in your terminal to list the leftover placeholder files. The [`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/en/errors#stale-sandbox-mask-files-left-by-a-killed-session) warning names some of them and counts the rest. Delete each file with `rm` while no other Claude Code session is running in that project. Before v2.1.257, Claude Code left the same placeholders behind when a session was killed, without flagging them.
910
902911### `git` over SSH fails with the sandbox on
903912
904913On macOS, `git fetch`, `git pull`, and `git push` against an SSH remote fail inside the sandbox even when the host is allowed. On Linux and WSL2, they work once the host is allowed. Claude Code tunnels git's SSH connection through the [sandbox proxy](#network-isolation), and the macOS tunnel can't authenticate to that proxy.
from line 1004
9951004An IP address entry with no port lets sandboxed commands reach every service listening on that address.
9961005
9971006Before v2.1.284, the proxy connected to whatever address an allowed hostname resolved to.
1007
1008### Commands are refused with `Sandbox is required`
1009
1010If you require the sandbox with [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) and it fails in one of these ways after Claude Code starts, each sandboxed command Claude runs is refused with the message shown. The session keeps running, and the refused command doesn't run unsandboxed:
1011
1012* **`Sandbox is required but failed to initialize: <reason>`**: Claude Code started, but the sandbox then failed to initialize. Take the step the message gives: `Restart to retry.` or `Fix the sandbox settings to retry`.
1013* **`Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>`**: on Linux or WSL2, the sandbox started and Claude Code then found a dependency missing. Fix what the reason names, such as [installing a missing dependency](#set-up-linux-and-wsl2), then restart Claude Code.
1014
1015Excluded commands and commands you type yourself keep running, and Claude can't retry a refused command unsandboxed:
1016
1017* **Excluded commands**: commands that match an [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) entry keep running outside the sandbox. When one writes to a [`filesystem.allowWrite`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowwrite) path outside your working directory, that write goes through the regular permission flow. Under an [admin-required sandbox](#repository-settings-under-an-admin-required-sandbox), Claude Code ignores entries from the repository's settings
1018* **Commands you type at the [`!` shell-mode prompt](https://code.claude.com/docs/en/interactive-mode#shell-mode-with-prefix)**: keep running outside the sandbox. In a [background session](https://code.claude.com/docs/en/agent-view.md), they're refused too
1019* **Unsandboxed retries**: Claude Code ignores the `dangerouslyDisableSandbox` parameter of an [unsandboxed retry](#the-unsandboxed-retry-escape-hatch)
1020
1021In a Linux session with `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` set, every command runs sandboxed, so excluded commands and commands you type are refused too.
9981022
9991023### `/sandbox` fails with `Sandbox settings are overridden by a higher-priority configuration`
10001024
No line in this hunk matches that.