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

> Learn how to configure the sandbox in Claude Code for enhanced security. Isolate Bash tool execution, restrict file system access and network activity with our comprehensive guide.

- Repository: [Anthropic/claude-code](https://github.com/anthropics/claude-code)
- Tags: security-guide
- Published: 2026-04-02

---

**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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json), this configuration enforces maximum security while maintaining sandbox integrity:

```json
{
  "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`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json):

```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:

```json
{
  "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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/settings.json) or [`managed-settings.json`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/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.