How to Configure the Sandbox in Claude Code: A Complete Security Guide

Claude Code runs the Bash tool inside an isolated sandbox when you enable the sandbox property in your settings JSON, restricting file-system access, network sockets, and command execution according to your defined security policies.

The anthropics/claude-code repository provides a lightweight, per-session sandbox environment that isolates Bash commands from your host system. According to the source code in examples/settings/README.md, the sandbox configuration block only affects the Bash tool—other tools like Read, Write, WebSearch, WebFetch, and MCPs operate outside the sandbox, as do hooks and internal commands.

Understanding the Sandbox Architecture

When active, the sandbox creates a temporary working directory (typically under /tmp/claude/) for all Bash execution. The file-system permission matrix—including allowRead, denyRead, allowWrite, and denyWrite—applies on top of the sandbox boundaries. This ensures that even inside the container, commands cannot write to protected locations such as .git, .claude, or the host's home directory unless explicitly allowed.

The sandbox restricts three primary vectors: file-system access, network sockets, and command execution privileges. Dependencies like rg, bash, and git must be available on the host; if missing, the runtime displays a visible startup warning or fails execution depending on your configuration.

Core Sandbox Configuration Options

Enabling the Sandbox

The presence of a sandbox object in your settings implicitly enables the feature. While sandbox.enabled is not an explicit boolean you must set, the runtime detects the configuration block and launches the sandbox before any Bash command executes.

Automatic Approval for Sandboxed Commands

sandbox.autoAllowBashIfSandboxed controls the permission flow. When set to true, Bash commands receive automatic approval (bypassing the "Ask user" prompt) only if the sandbox starts successfully. This allows you to maintain strict security while reducing friction for safe, contained execution.

Blocking Unsandboxed Fallback

Two critical settings prevent accidental unsandboxed execution:

sandbox.allowUnsandboxedCommands – When set to false, this disables the escape-hatch dangerouslyDisableSandbox at the policy level. Any request to run Bash without sandboxing is rejected rather than presenting a bypass option.

sandbox.failIfUnavailable – Added in v2.1.77 (as documented in CHANGELOG.md), this boolean forces the agent to error out if the sandbox cannot be started, instead of silently falling back to unsandboxed execution.

Command Exclusions

sandbox.excludedCommands accepts an array of command-prefix patterns that bypass the sandbox. For example, ["git:*"] allows all Git commands to run unsandboxed. These excluded commands still trigger the normal permission-ask flow unless autoAllowBashIfSandboxed is enabled.

Network Restrictions

The sandbox.network object provides fine-grained control over connectivity:

• allowUnixSockets – Array of allowed Unix socket paths (e.g., ["/var/run/docker.sock"])
• allowAllUnixSockets – Boolean to permit all Unix sockets
• allowLocalBinding – Boolean to allow local port bindings
• allowedDomains – Array of permitted outbound domains (e.g., ["api.github.com"])
• httpProxyPort and socksProxyPort – Proxy configuration integers

macOS Nested Sandbox Relaxation

sandbox.enableWeakerNestedSandbox is a macOS-only boolean that relaxes nested-sandbox restrictions required by certain Go-based CLI tools like gh, gcloud, and terraform. Enable this only when necessary, as it reduces isolation strength.

Configuration Examples

Strict Enterprise Configuration

As implemented in examples/settings/settings-strict.json, this configuration enforces maximum security while maintaining sandbox integrity:

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "ask": ["Bash"],
    "deny": ["WebSearch", "WebFetch"]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "sandbox": {
    "autoAllowBashIfSandboxed": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

This setup requires manual approval for every Bash command while blocking all network access and Unix socket usage within the sandbox.

Enforcing Sandbox-Only Execution

To guarantee that Bash never runs unsandboxed, use the pattern from examples/settings/settings-bash-sandbox.json:

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "failIfUnavailable": true
  }
}

With allowUnsandboxedCommands set to false and failIfUnavailable enabled, the agent aborts the session entirely if sandbox startup fails, preventing accidental exposure.

Network Access Control

To permit specific domains and Docker socket access while maintaining other restrictions:

{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowAllUnixSockets": false,
      "allowLocalBinding": true,
      "allowedDomains": ["api.github.com", "registry.npmjs.org"],
      "httpProxyPort": null,
      "socksProxyPort": null
    }
  }
}

This configuration allows outbound HTTPS only to GitHub and npm registries while enabling Docker CLI functionality through the Unix socket.

Interactive Sandbox Management

You can inspect and manage the sandbox directly from the Claude Code interface by typing /sandbox. This command opens the sandbox control panel, which displays dependency status (verifying availability of rg, bash, and git) and provides buttons to install missing Linux or macOS prerequisites. The UI references the same JSON schema documented in examples/settings/README.md, ensuring consistency between file-based and interactive configuration.

Summary

• The sandbox isolates only the Bash tool; other Claude Code tools remain unaffected by sandbox settings.
• Enable sandboxing by adding a sandbox object to your settings.json or managed-settings.json.
• Prevent unsandboxed fallback using allowUnsandboxedCommands: false and failIfUnavailable: true (v2.1.77+).
• Control network access through the sandbox.network object, specifying allowed domains, Unix sockets, and proxy ports.
• Use /sandbox in the UI to verify dependencies and troubleshoot configuration issues in real time.

Frequently Asked Questions

What happens if sandbox dependencies are missing?

If required dependencies like rg, bash, or git are unavailable, Claude Code displays a visible startup warning. If you have enabled sandbox.failIfUnavailable (added in v2.1.77), the agent errors out instead of falling back to unsandboxed execution.

Does the sandbox affect tools other than Bash?

No. According to the source code in examples/settings/README.md, the sandbox property applies only to the Bash tool. Other tools—including Read, Write, WebSearch, WebFetch, MCPs, hooks, and internal commands—operate outside the sandbox environment regardless of your configuration.

How do I allow specific commands to bypass the sandbox?

Use the sandbox.excludedCommands array with command-prefix patterns. For example, ["git:*"] routes all Git commands outside the sandbox. Note that excluded commands still trigger permission prompts unless autoAllowBashIfSandboxed is enabled.

What is the difference between allowUnsandboxedCommands and failIfUnavailable?

allowUnsandboxedCommands controls policy-level access to the dangerouslyDisableSandbox escape hatch; when false, users cannot request unsandboxed execution. failIfUnavailable determines runtime behavior when the sandbox fails to start; when true, the session aborts rather than silently running commands on the host.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}