Configure the sandboxed Bash tool - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. The Bash sandbox is a boundary that the operating system enforces around the shell commands Claude runs on your machine. You set which files and network domains those commands can reach, and the limits apply to Bash, PowerShell, and Monitor commands and the processes they start.
Sandboxed commands still go through the regular permission flow unless you choose auto-allow mode , which can run them without asking you. The sandbox covers shell commands only. Claude’s file tools, MCP servers, and hooks run outside it . The sandbox runs on macOS, Linux, and WSL2. On native Windows, Claude Code runs commands unsandboxed. To use the sandbox on a Windows machine, run Claude Code inside a WSL2 distribution.
This page covers the sandbox around shell commands on your own machine. Other pages cover related questions: For how a cloud session is isolated, see Security and isolation To compare other isolation approaches such as dev containers, custom containers, and virtual machines, see Sandbox environments To reduce permission prompts for tools other than Bash, see permission modes What the sandbox restricts While the sandbox is on, the shell commands Claude runs start inside its boundary, and so do the processes they start.
The sandbox is off by default. To turn it on, run /sandbox in a session, as Get started shows, or set sandbox.enabled to true in a settings file such as ~/.claude/settings.json . The table shows what a sandboxed command can reach by default and the settings that change each default. Access Default Change it with Writes The working directory, a per-user temp directory, and directories you’ve added . Protected paths stay write-denied filesystem.allowWrite , filesystem.denyWrite Reads Most of the machine, including credential files such as ~/.ssh and ~/.aws/credentials filesystem.denyRead , credentials Network No direct route out.
Connections go through a proxy on your machine that checks each host against your allowed domains, which start empty. Your permission mode decides what happens to other hosts network.allowedDomains , network.deniedDomains Environment variables Inherited from Claude Code, including any secrets in its environment credentials , CLAUDE_CODE_SUBPROCESS_ENV_SCRUB Claude Code builds the sandbox on the open source @anthropic-ai/sandbox-runtime package.
What runs outside the sandbox The sandbox wraps shell commands. These tools and processes run outside it: Built-in file and web tools : tools such as Read, Edit, Write, WebFetch, and WebSearch follow permission rules instead. A denyRead entry doesn’t stop the Read tool, and allowedDomains doesn’t limit WebFetch Other processes Claude Code starts : command hooks , local MCP servers , plugin monitors , LSP servers , and helper commands such as your status line command and apiKeyHelper run with your full access Mods : a mod runs its own code inside Claude Code, so its file access, network requests, and programs started with $.process aren’t sandboxed.
See What a mod can reach Some shell commands also run outside the sandbox, depending on your settings: Commands you type yourself : a command you enter at the ! shell-mode prompt runs unsandboxed in most sessions. Strict sandbox mode lists the sessions where a command you type runs sandboxed Excluded commands : commands that match excludedCommands run unsandboxed Unsandboxed retries : Claude can ask to run a command unsandboxed , usually after it fails in the sandbox To put the tools, processes, and commands in this section behind one boundary, run the Claude Code process itself in a container, virtual machine, or the sandbox runtime .
Get started The sandbox is built into Claude Code. What you install depends on your platform: macOS : sandboxing uses the built-in Seatbelt framework, so you can go straight to the steps Linux and WSL2 : the sandbox relies on bubblewrap and socat , covered in 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 1 Run /sandbox Start a Claude Code session and run the /sandbox command: /sandbox This opens the sandbox panel with three tabs, plus a Dependencies tab on Linux when the optional seccomp filter is missing: Mode : choose how sandboxed commands are approved, covered in the next step Overrides : choose whether commands that fail under the sandbox can fall back to running unsandboxed.
This is the allowUnsandboxedCommands setting Config : view the resolved sandbox settings If 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 , restart Claude Code, and run /sandbox again. 2 Choose a mode 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 for which commands still prompt in auto-allow mode. 3 Run a Bash command Ask Claude to run a command, such as a build or a test suite. By default, commands inside the sandbox can write to the working directory, a per-user temp directory , and any directories you’ve added with --add-dir , /add-dir , or permissions.additionalDirectories . The first time a command needs a new network domain, Claude Code prompts for approval; in auto mode , Claude instead names the hosts a command needs on the command itself for the classifier to review with it.
To widen or narrow what the sandbox allows, see Configure sandboxing . If sandboxed commands fail with Operation not permitted inside a container, see Bubblewrap fails to start inside a container . When you select a mode in the panel, Claude Code saves it to your project’s local settings at .claude/settings.local.json , which apply to the current project. Claude Code adds that file to your global gitignore when it saves a setting there.
To enable the sandbox across all of your projects, set sandbox.enabled to true in your user settings at ~/.claude/settings.json . To enforce sandboxing for every developer in an organization, use managed settings . To change the sandbox for one session without writing to a settings file, start Claude Code with --settings . For example, this command starts a sandboxed session in which Claude can’t retry a blocked command outside the sandbox: claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}' 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 to true . Managed deployments that require sandboxing as a security gate can use this setting. Confirm commands run inside the sandbox To check that the sandbox is working, ask Claude to run each line in the table. What you type at the ! prompt usually runs outside the sandbox, so typing a line yourself doesn’t test it. Command Result inside the sandbox touch ~/sandbox-probe Fails with Operation not permitted on macOS, or Read-only file system on Linux and WSL2 curl --noproxy '*' https://example.com Fails with Could not resolve host , because the command has no route around the sandbox proxy If Claude asks to retry a failed command outside the sandbox, decline the retry.
If touch succeeds and your home directory isn’t one of the directories the sandbox lets commands write to, delete ~/sandbox-probe . Then run /sandbox to check that the sandbox is on and its dependencies are installed. Set up Linux and WSL2 On Linux and WSL2, the sandbox relies on these packages: bubblewrap : the unprivileged sandboxing tool that enforces filesystem isolation socat : the re
The rest of this page is on the live site.