Configuring Sandbox Mode with File and Network Isolation in Claude Code

Enabling sandbox mode in Claude Code's settings.json automatically approves Bash commands while restricting filesystem and network access, eliminating repetitive permission prompts without sacrificing security.

Configuring sandbox mode with file and network isolation allows Claude Code to execute Bash commands in a restricted runtime that validates file access and outbound connections before execution. According to the source code in shanraisshan/claude-code-best-practice, the sandbox configuration resides in the top-level sandbox key of your project's settings.json file, as documented in best-practice/claude-settings.md. This deterministic validation pipeline blocks unauthorized I/O operations and network calls, reducing the need for interactive permission prompts during routine development tasks.

Enabling the Sandbox Runtime

The sandbox is disabled by default. To activate the restricted runtime, set sandbox.enabled to true in your .claude/settings.json file.

{
  "sandbox": {
    "enabled": true
  }
}

When enabled, all Bash commands run inside the sandbox container rather than directly on the host. By default, sandbox.autoAllowBashIfSandboxed remains true, which means sandboxed commands are automatically approved without prompting the user, provided they do not violate configured filesystem or network rules.

Filesystem Isolation Configuration

The sandbox controls file access through path-prefix rules defined under sandbox.filesystem. These rules are evaluated before command execution, aborting any operation that attempts to access unauthorized paths.

Path Prefix Syntax

Claude Code uses specific prefix conventions to define scope in best-practice/claude-settings.md:

• // – Absolute path from system root (e.g., //etc/passwd)
• ~/ – User's home directory
• / – Project root (where the .claude folder exists)
• ./ – Current working directory for the specific Bash invocation

Write Whitelists and Deny Lists

Use sandbox.filesystem.allowWrite to specify the only locations a sandboxed command may modify. Complement this with denyWrite and denyRead to explicitly forbid access to sensitive paths, overriding broader allow rules.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["./generated/", "./dist/"],
      "denyRead": ["./secrets/"],
      "denyWrite": ["./.env", "~/ssh/"]
    }
  }
}

In this example, sandboxed commands may write only to ./generated/ and ./dist/. Attempts to modify ./.env or read from ./secrets/ trigger a sandbox-violation error before the command executes.

Network Isolation Controls

Network restrictions prevent sandboxed commands from leaking data or connecting to unauthorized hosts. These checks occur outside the container running the Bash command, ensuring processes cannot bypass the firewall.

Domain Whitelisting and Blacklisting

Control outbound HTTP connections using sandbox.network.allowedDomains and sandbox.network.deniedDomains. Deny lists take precedence over allow lists.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["api.example.com", "registry.npmjs.org"],
      "denyDomains": ["telemetry.badhost.com"]
    }
  }
}

This configuration blocks all external network calls except those to api.example.com and registry.npmjs.org, while explicitly forbidding telemetry.badhost.com even if it were accidentally whitelisted elsewhere.

Unix Socket and Local Binding Options

For container workflows or local services, configure socket access and localhost binding:

• sandbox.network.allowUnixSockets – Array of specific Unix-socket paths (e.g., /var/run/docker.sock)
• sandbox.network.allowAllUnixSockets – Boolean shortcut to permit any Unix socket
• sandbox.network.allowLocalBinding – Permit binding to localhost ports (macOS only)

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

Advanced Sandbox Tuning

Fine-tune sandbox behavior to accommodate specific workflows without sacrificing the auto-approval benefits.

Command Exclusions and Auto-Approval

Certain tools require full host access to function correctly. Use sandbox.excludedCommands to run specific binaries outside the sandbox, or set allowUnsandboxedCommands to false to disable the dangerouslyDisableSandbox escape hatch.

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": false
  }
}

Here, git and docker execute with full filesystem and network access, while all other commands remain sandboxed. Setting allowUnsandboxedCommands to false prevents users from bypassing the sandbox for one-off commands.

Violation Suppression

Repeated sandbox warnings for known-safe patterns clutter the interface. Map command patterns to file-path arrays in sandbox.ignoreViolations to suppress specific warnings.

{
  "sandbox": {
    "enabled": true,
    "ignoreViolations": {
      "Bash(git push *)": ["./.git/"]
    }
  }
}

This entry silences warnings when git push commands access the ./.git/ directory, which would otherwise trigger a sandbox violation notification.

Execution Flow and Architecture

When a user invokes /bash <command> or a Skill triggers Bash, Claude Code follows a deterministic pipeline as implemented in the repository:

1. Sandbox check – If sandbox.enabled is false, the command runs directly on the host.
2. Command classification – If the command matches sandbox.excludedCommands, it bypasses the sandbox.
3. File-access validation – Read/write operations are compared against filesystem allow/deny lists.
4. Network validation – Outbound connections are checked against domain and socket rules.
5. Execution – Validated commands run inside the sandbox container.
6. Result handling – Only summary text enters the conversation history; raw output remains sandboxed unless explicitly returned by a Skill.

This architecture ensures that routine operations proceed without interruption while potentially risky commands are blocked deterministically.

Complete Configuration Example

The following production-ready configuration from .claude/settings.json demonstrates combined file and network isolation:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true,
      "allowedDomains": ["api.mycompany.com"],
      "deniedDomains": ["telemetry.badhost.com"]
    },
    "filesystem": {
      "allowWrite": ["./dist/", "./logs/"],
      "denyRead": ["./secrets/"],
      "denyWrite": ["./.env"]
    },
    "ignoreViolations": {
      "Bash(git push *)": ["./.git/"]
    }
  }
}

This setup permits builds in ./dist/, allows Docker socket access for container operations, restricts network calls to internal APIs, and blocks secret exposure—all while keeping git and docker unsandboxed for version control workflows.

Summary

• Enable the sandbox by setting sandbox.enabled to true in .claude/settings.json to activate the restricted runtime.
• Configure file isolation using path prefixes (/, ./, //, ~/) in sandbox.filesystem to whitelist write locations and deny access to sensitive paths.
• Restrict network access via sandbox.network.allowedDomains and deniedDomains, with additional controls for Unix sockets and localhost binding.
• Reduce permission prompts by leveraging sandbox.autoAllowBashIfSandboxed, which automatically approves sandboxed commands that pass validation.
• Exclude necessary tools like git or docker using sandbox.excludedCommands when sandboxing interferes with their operation.

Frequently Asked Questions

How do I completely disable permission prompts for Bash commands?

Set sandbox.enabled to true and keep sandbox.autoAllowBashIfSandboxed at its default value of true. This configuration automatically approves all Bash commands that run inside the sandbox, provided they do not violate your filesystem or network rules. Commands that violate the sandbox policy are blocked with an error rather than prompting for permission.

Can I allow specific directories while blocking all others?

Yes. Use sandbox.filesystem.allowWrite to define an array of permitted path prefixes using the ./ (current working directory), / (project root), // (absolute), or ~/ (home) syntax. Any write attempt outside these prefixes is automatically denied. For example, "allowWrite": ["./build/", "./temp/"] restricts writes to only those two directories relative to the project root.

What happens if a sandboxed command tries to access a blocked domain?

The sandbox runtime intercepts the network connection attempt before it leaves the container. If the domain is not listed in sandbox.network.allowedDomains or is explicitly listed in sandbox.network.deniedDomains, the command aborts with a sandbox-violation error. This check occurs outside the Bash process, preventing the command from bypassing restrictions even if it attempts to circumvent the firewall.

Is it possible to run some commands outside the sandbox while keeping others restricted?

Yes. Use the sandbox.excludedCommands array to list command names (e.g., "git", "docker") that should execute with full host access. These commands bypass the sandbox entirely, while all other Bash invocations remain subject to file and network isolation. Alternatively, set sandbox.allowUnsandboxedCommands to false to disable the per-command escape hatch and enforce sandboxing universally.

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