Contents
- The bottom line in 30 seconds
- 1. Why you need a sandbox
- 2. What the sandbox is — two isolations
- 3. Getting started — /sandbox and supported OSes
- 4. The two modes (auto-allow / regular)
- 5. Configuring it in settings.json
- 6. Relationship to permission modes and rules
- 7. Limits and caveats — do not over-trust it
- 8. When to reach for dev containers or VMs
- Summary
- FAQ
With settings that produce frequent confirmations in Claude Code, approving commands can interrupt your work. Yet disabling confirmations with --dangerously-skip-permissions (bypass permissions) means prompt injection or mistakes could affect files across your machine. Reducing prompts still requires deciding which scope to allow.
The sandbox restricts, at the OS level, which files and network destinations shell commands and their child processes can access. Turning on auto-allow mode helps reduce confirmations, but does not guarantee protection of the whole machine or prevention of data leaks. This article explains its scope, settings, conditions for skipping confirmation, and routes outside the sandbox.
The bottom line in 30 seconds
If you only read one thing
/sandbox. macOS works out of the box; Linux/WSL2 needs two packages.* Anthropic reports that the sandbox reduced permission prompts by 84% in its internal use (source below).
1. Why you need a sandbox
Claude Code is an AI agent that actually does things — running tests and rewriting files. Depending on its permission settings, it asks for approval before execution. But when dozens of prompts land in a day, work fragments, and eventually you hit Enter without reading. That is "permission fatigue."
A tired developer reaches for --dangerously-skip-permissions (a.k.a. YOLO mode), which turns off all prompts. It is comfortable, and — as the name says — dangerous. Three threats bare their teeth at once.
If a web page or issue it reads hides "send ~/.ssh," your private keys can leak with no prompt.
A generated command cleans an unexpected path. Without a prompt, files outside the project can vanish too.
A malicious dependency phones data out on install. With the network wide open, you cannot stop it.
Separate from approving a command string, the sandbox limits what a running process can reach. OS restrictions also apply to arbitrary scripts, but do not prevent misuse of allowed write locations or destinations. In its official engineering post, Anthropic reported an 84% reduction in internal permission prompts (October 2025). This is the vendor's internal measurement, not a guarantee of the reduction or safety in every environment.
2. What the sandbox is — two isolations
The Claude Code sandbox applies two boundaries to Bash, PowerShell, and Monitor shell commands and child processes. Both must work together; either alone leaves gaps (see §7).
Default write locations are the working directory, additional working directories, and per-user temporary storage. Protected paths are denied separately. Reads are broadly allowed by default, so secrets need restrictions such as denyRead. Deletion and modification in writable areas remain possible.
Connections pass through a proxy and are checked against allowed domains. The list starts empty, but settings and permission rules add entries. Handling of hosts outside the list depends on the permission mode; it does not always mean rejection or confirmation. Sending secrets to an allowed destination is not guaranteed to be blocked.
The crux is that it does not rely on Claude behaving well. The boundary is enforced by the OS's own security machinery — macOS uses the built-in Seatbelt, Linux/WSL2 uses bubblewrap. So the same boundary extends to scripts a command invokes and to grandchild processes. Rather than a request to the model, like AI guardrails, it is a restriction on process access enforced by the OS.
💡 It covers shell commands and child processes. The sandbox wraps Bash, PowerShell, and Monitor shells and their child processes. Built-in Read/Edit/Write, MCP servers, and hooks are separate, controlled by permission rules. To isolate the whole process, consider @anthropic-ai/sandbox-runtime, discussed below.
3. Getting started — /sandbox and supported OSes
The sandbox is built into Claude Code. No extra account is required, but depending on the OS, you need to prepare dependency packages. In a session, run:
/sandbox
A panel opens with three tabs. Mode (how sandboxed commands are approved — next section), Overrides (whether a command that fails under the sandbox may fall back to running unsandboxed), and Config (view the resolved settings). On Linux/WSL2, if a required package is missing, a Dependencies tab appears instead and tells you what to install.
Prerequisites per OS
Nothing to install. It uses the built-in Seatbelt. Enable it right away with /sandbox.
Install two packages: bubblewrap and socat (e.g. apt-get install bubblewrap socat).
Not supported. Run Claude Code inside WSL2 (WSL1 will not work).
On Linux/WSL2, install bubblewrap (the unprivileged sandboxing tool that enforces filesystem isolation) and socat (the relay that routes traffic to the proxy).
# Ubuntu / Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat
⚠️ Ubuntu 24.04 and later: the default AppArmor policy can stop bubblewrap from creating the user namespaces it needs. If sysctl kernel.apparmor_restrict_unprivileged_userns returns 1, add an AppArmor profile for bwrap to grant it (the steps are in the official docs). If it returns 0 or the key does not exist, no action is needed. Check the same inside WSL2.
One handy thing to enable is the seccomp filter (which adds Unix-domain-socket blocking). It is optional; install it with npm install -g @anthropic-ai/sandbox-runtime. The /sandbox Dependencies tab shows the status of ripgrep, bubblewrap, socat, and the seccomp filter. After installing packages, restart Claude Code and reopen /sandbox (the check runs at startup).
On Linux/WSL2, commands inside the sandbox cannot create user namespaces by default. To let Chromium or Electron's own sandbox, or a nested bubblewrap or unshare, run, set sandbox.allowNestedUserNamespaces to true in ~/.claude/settings.json (v2.1.305 and later; it cannot be enabled in project settings). However, the official docs warn that this opens one security boundary. That is because code in a sandboxed command may be able to run outside the sandbox. rootless Podman and Buildah do not work with this setting alone (official explanation).
4. The two modes (auto-allow / regular)
The Mode tab chooses how commands inside the sandbox are approved.
The default is regular permissions mode (from v2.1.324). Turning on the sandbox alone still shows the same confirmations for commands it isolates. Up to v2.1.323, auto-allow was the default. To reduce confirmations, choose auto-allow in the Mode tab, or set sandbox.autoAllowBashIfSandboxed: true in settings.json (official settings reference). Organizations that require the sandbox through managed settings should set the same value in the highest-priority managed setting.
Sandboxed shell commands are normally approved without confirmation. Applicable deny rules, content-scoped ask rules, and critical-path deletion checks remain. The decision about an unknown destination is separate from the decision to retry a command outside the sandbox. Neither always prompts.
Even when sandboxed, shell commands go through ordinary permission evaluation. This adds control and can add approvals. It suits a cautious workflow that combines isolation with ordinary confirmation checks.
In both modes the filesystem and network boundaries are identical; the only difference is "auto-allow versus prompt." Note that even in auto-allow mode these safety valves stay live:
- Among settings rules, a matching deny takes precedence over allow. For conditions where mods change decisions, see the permission rules guide.
rm/rmdirtargeting/, the home directory, or critical system paths prompt or are rejected according to the permission mode- Content-scoped ask rules like
Bash(git push *)still force a prompt, even inside the sandbox
Beware two confusingly similar “autos.” The sandbox's auto-allow mode differs from the auto mode of permission modes. The former automatically approves commands contained by the OS boundary; the latter uses a classifier to review command safety. They can be combined, but in Plan, auto-allow does not expand the scope of approval. Auto's host review and additional classifier review can also remain under some conditions.
Communication with an unknown destination
In an interactive terminal, Manual, acceptEdits, and ordinary Plan prompt; dontAsk rejects. Auto allows hosts named in the command when the classifier approves them. Bypass and Plan with bypass available for selection allow them without confirmation. Rejections from strictAllowlist, allowManagedDomainsOnly, and deniedDomains apply separately. The command itself remains inside the sandbox.
Retrying outside the sandbox
In an interactive terminal, Manual and acceptEdits normally prompt, auto uses the classifier, and dontAsk rejects. Plan follows command evaluation for Plan. Bypass or a matching allow skips confirmation, but an ask rule for Bash(dangerouslyDisableSandbox:true), restrictions on reads outside the workspace, or other checks can take precedence. allowUnsandboxedCommands:false blocks retries; excludedCommands is separate. failIfUnavailable prevents running without isolation when the sandbox is unavailable. Check the official exception conditions too.
5. Configuring it in settings.json
Choices in the /sandbox panel are written to the project's .claude/settings.local.json (not committed to git). To keep it always on across all projects, put sandbox.enabled: true in your user settings at ~/.claude/settings.json. To reduce confirmations, also add autoAllowBashIfSandboxed: true inside the same sandbox object (the default is false, regular permissions mode). It lives in the same settings.json family as permission rules (allow/ask/deny).
Add write targets, deny reads
Default write locations are the working directory, additional working directories, and per-user temporary storage. allowWrite adds further locations. denyRead limits reads by sandboxed commands; it does not directly block the built-in Read tool or MCP.
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"],
"denyRead": ["~/"],
"allowRead": ["."]
}
}
}
The example above denies reads of the whole home directory while still allowing the current project (. resolves to the project root when the config lives in project settings). Paths are enforced at the OS level, so they apply equally to child processes like npm and terraform.
Protect credentials
An important pitfall: the default for reads is "broadly allowed," so ~/.aws/credentials and ~/.ssh/ are readable as-is. The dedicated sandbox.credentials setting (a relatively recent feature) declares files to deny reading and environment variables to unset.
{
"sandbox": {
"enabled": true,
"credentials": {
"files": [
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.ssh", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" }
]
}
}
}
Allow destinations
The allowed-domain list starts empty, but entries are added through allowedDomains, WebFetch domain rules, and other settings. Unknown destinations can prompt, be rejected, or be allowed without confirmation, depending on the permission mode. If destinations must form an enforced boundary, also check strictAllowlist and managed allowManagedDomainsOnly.
{
"sandbox": {
"enabled": true,
"network": {
"allowedDomains": ["*.github.com", "registry.npmjs.org"]
}
}
}
To require it organization-wide. In managed settings, sandbox.enabled: true, failIfUnavailable: true (refuse to start Claude Code if the sandbox cannot initialize), and allowUnsandboxedCommands: false (close the unsandboxed retry escape hatch) restrict execution without isolation when the sandbox is unavailable and retries outside it. However, excludedCommands, built-in file tools, MCP, and other routes are separate; these settings alone do not guarantee isolation of every operation.
6. Relationship to permission modes and rules
They are easy to conflate, but Claude Code's safety machinery has three layers with distinct jobs. The sandbox is one of them — it does not replace the other two; it complements them.
| Layer | What it controls | Enforced by | Scope |
|---|---|---|---|
| Permission rules | Which tools/commands may be used | Claude Code (before running) | All tools |
| Permission modes | How many prompts appear | Claude Code (before running) | Depends on mode |
| Sandbox | What it can touch once it runs | The OS (kernel) | Shell commands and child processes |
Permission rules evaluate tool calls before execution; the sandbox restricts file and network access by processes running inside it. This has the advantage of not depending on alternate command spellings. However, tools outside it, excluded commands, unsandboxed retries, and broad permissions leave routes where the same boundary does not apply.
Bypass is a permission mode that skips confirmations and the classifier; the sandbox is a layer that restricts execution scope. They serve different roles. Even together, bypass can allow unknown hosts and unsandboxed retries without confirmation under some conditions. Do not assume that everyday use on your own machine is safe; check allowed scope, exceptions, and credentials together.
7. Limits and caveats — do not over-trust it
The sandbox is powerful, but it is not complete isolation. Before leaning on it as a hard security boundary, know the limits the docs spell out.
The proxy judges on hostname only and does not inspect encrypted content (by default). Allowing a broad domain like github.com leaves room to exfiltrate data via domain fronting and the like. Keep the allowlist narrow.
Allowing /var/run/docker.sock hands over the whole host via the Docker socket — effectively a sandbox escape. Be careful which sockets you open.
Writable executables on $PATH or files like .bashrc can turn into code execution in another context. Keep allowWrite minimal.
Built-in Read/Edit/Write, WebFetch/WebSearch, MCP, hooks, LSP, and helper commands run outside the built-in sandbox. To restrict the whole process, consider another boundary such as a container, VM, or sandbox-runtime. Allowed mounts, network access, sockets, and credentials matter there too.
8. When to reach for dev containers or VMs
The sandbox is not Claude Code's only isolation option. Convenience and strength of isolation trade off, so choose by purpose.
Isolates shell commands and child processes. No Docker, minimal setup. With auto-allow mode, a main option for reducing prompts in daily development.
Wraps Claude Code and the local child processes it starts. Isolating a remote MCP server itself is a separate matter. No Docker.
Containerizes the whole dev environment. For standardizing a team's setup. Requires Docker.
Separates the whole OS using a guest operating system. Shared folders, networking, and credentials need careful configuration. An option for untrusted code, with the most setup effort.
The rule of thumb: keep the built-in sandbox always on, use auto-allow mode to cut daily prompts, and only step up to sandbox-runtime, containers, or VMs when you run unattended or handle untrusted dependencies. For work that reaches production — like letting AI operate the cloud — pairing least-privilege credentials with a stronger isolation tier buys peace of mind.
Summary
- The sandbox fences "what can be touched" at the OS level, dissolving the binary of prompt fatigue versus full bypass.
- Use filesystem and network isolation as a set. Enforcement: macOS = Seatbelt, Linux/WSL2 = bubblewrap.
- Start with
/sandbox. macOS works out of the box; Linux/WSL2 needsbubblewrap+socat; native Windows is unsupported (use WSL2). - The default is regular permissions mode (from v2.1.324). To reduce confirmations, choose auto-allow mode. Even without confirmations, modification and transmission within allowed areas remain possible. Deny rules, risky
rm, and content-scoped ask rules remain. - It is a complementary layer with a different role from permission rules and modes. The OS restricts access during execution. Routes outside the sandbox are separate.
- It is not a complete wall: watch uninspected TLS, Unix sockets, and overly broad permissions. It covers sandboxed shells and child processes.
When reducing confirmations, check allowed scope and routes outside the sandbox first. For the exact, current configuration reference, treat the official sandbox settings documentation as your primary source.
FAQ
Q. How is the sandbox different from --dangerously-skip-permissions?
A. Bypass skips confirmations and the classifier. The sandbox limits what sandboxed shells and child processes can reach. Built-in file tools and MCP are outside it, and modifications or transmissions within allowed areas remain possible. Combined use can also allow unknown hosts or unsandboxed retries without confirmation, so it does not make the whole machine safe.
Q. Can I use it on Windows?
A. Native Windows is unsupported; use it inside WSL2. Restrictions on access to Windows binaries depend on seccomp and Unix socket settings, so it is not correct to say they can never be launched. Commands in excludedCommands run outside the sandbox; check their impact separately.
Q. Will enabling it slow things down?
A. This review did not establish a performance measurement applicable to all environments. Fewer confirmations and shorter command execution times are separate outcomes. Compare the same build or test while recording elapsed time, approval counts, and failures.
Q. With the sandbox on, are my private keys guaranteed safe?
A. No absolute guarantee. The default for reads is broad, so ~/.ssh and ~/.aws/credentials are readable by default. Restrict reads by sandboxed shells with sandbox.credentials or denyRead, and keep the network allowlist narrow. Built-in Read and MCP need separate controls. Disabling filesystem isolation with filesystem.disabled:true makes denyRead and credential-file deny settings ineffective. Filesystem and network isolation must work together.
Q. Are MCP servers and hooks sandboxed too?
A. The built-in sandbox covers Bash, PowerShell, and Monitor shell commands and child processes. MCP, hooks, and built-in Read/Edit/Write run outside it. If you consider sandbox-runtime, containers, or VMs to wrap the whole process, separately check the permitted network access, mounts, and credentials in that environment.
If you want investigation and advice without changes, see how to use Codex and Claude Code for investigation only. The sandbox permits workspace writes by default, so distinguish it from read-only access.
The scope and exception conditions for permissions and isolation were rechecked against official source documentation on October 9, 2026. No device settings were changed and no startup tests were performed.