Skip to main content
The 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.
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.

​
Get started

The 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. On 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. 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:
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, a required package is missing. Install it 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 only to the working directory and the session temp directory. The first time a command needs a new network domain, Claude Code prompts for approval, or in auto mode sends the request to the classifier.Commands that cannot run sandboxed fall back to the regular permission flow. To widen or narrow these boundaries, see Configure sandboxing.
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.
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 to true. This is intended for managed deployments that require sandboxing as a security gate.

​
Set up Linux and WSL2

On Linux and WSL2, the sandbox relies on two packages:
  • bubblewrap: the unprivileged sandboxing tool that enforces filesystem isolation
  • socat: the relay used to route network traffic through the sandbox proxy
Install them with your distribution’s package manager: