# Configuring Sandbox Mode with File and Network Isolation in Claude Code

> Configure Claude Code sandbox mode for secure file and network isolation. Reduce permission prompts and enhance security with this essential setting.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: how-to-guide
- Published: 2026-03-12

---

**Enabling sandbox mode in Claude Code's [`settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/settings.json) file, as documented in [`best-practice/claude-settings.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json) file.

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.

```json
{
  "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.

```json
{
  "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)

```json
{
  "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.

```json
{
  "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.

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json) demonstrates combined file and network isolation:

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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.