# Claude Code Sandboxing and isolation

> Claude Code: Bash sandbox, full-process runtime, dev containers, Docker, VMs, hosted execution, permissions, networking, and credentials.

URL: https://docs.passion8.cc/en/docs/claude-code/sandboxing
Language: en
Publisher: Passion8

Permissions decide whether a command may execute; isolation limits the files, networks, and credentials it can reach afterward. Consider both for automatic execution and unfamiliar repositories.




Sandboxing does not change model data flow. Read prompts/files still go to Anthropic, Passion8, or the configured provider.




## Compare isolation options

| Option | Scope | Docker required | Use |
| --- | --- | --- | --- |
| Bash sandbox | Shell commands and children | No | Fewer routine prompts |
| Sandbox runtime | Entire Code process, MCP, hooks | No | Full-process isolation without Docker |
| Dev container | Development environment | Yes | Standardized team/unattended work |
| Custom container | Development environment | Yes | Existing CI/remote infrastructure |
| VM | Operating system | No | Untrusted code or stronger boundaries |
| Hosted web | Anthropic-managed VM | No | Delegated browser/mobile work |

The Bash sandbox does not include built-in Read/Edit, MCP servers, or hooks. Use a full-process runtime, container, or VM to include them.

## Relationship to permissions

| Layer | Controls | Configuration |
| --- | --- | --- |
| Rules | Tools, paths, commands, domains | permissions.allow/deny |
| Mode | Approval behavior | default, plan, auto, bypass |
| Sandbox | Post-launch access | sandbox filesystem/network |

Skipping permission prompts should be reserved for appropriate isolation. Auto mode's classifier is not an operating-system boundary.

## Enable the Bash sandbox





### Open the panel


```text
/sandbox
```

The panel shows Mode, Overrides, and Config. Linux/WSL2 checks bubblewrap and socat dependencies.



### Choose a mode

Auto-allow automatically runs commands constrained by the sandbox. Regular permissions retains normal approval while still isolating execution.



### Run a test command

Default writes are limited to the working directory and session temporary directory. New domains prompt. Disable unsandboxed fallback for a stricter boundary.






Linux/WSL2 dependencies:

```bash
sudo apt-get install bubblewrap socat
```

Fedora:

```bash
sudo dnf install bubblewrap socat
```

Native Windows does not support this Bash sandbox; use WSL2, containers, or a VM.

## Common settings

Require an available sandbox:

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

Allow selected write directories:

```json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}
```

Default reads may still reach home-directory credentials. Protect them explicitly:

```json
{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}
```

Credential masking can preserve authentication without exposing the real token, but requires supported TLS termination/domain policy. Configure it in user, CLI, or managed settings, not an untrusted project.

## Network control

A proxy controls command network access. New destinations normally require approval. Teams can define allowed domains and lock them with managed policy:

```json
{
  "sandbox": {
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "*.github.com",
        "passion8.cc"
      ]
    }
  }
}
```

Use allowManagedDomainsOnly to prevent widening the managed list. Stronger enterprise inspection may require a custom TLS-terminating proxy; hostname allowlists alone do not inspect encrypted content.

## Enforced organization policy

MDM, system-managed, or server-managed settings can enforce:

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

Also consider:

- Credential restrictions for SSH/cloud/package-manager secrets.
- allowManagedReadPathsOnly to prevent local widening.
- allowManagedDomainsOnly for network policy.
- A minimal excludedCommands list.

See [Enterprise administration](https://docs.passion8.cc/en/docs/claude-code/enterprise-admin).

## Common failures

| Symptom | Action |
| --- | --- |
| Host not allowed | Approve/add the intended domain |
| Jest hangs | Try --no-watchman |
| Docker fails | Docker socket access weakens isolation; use deliberate exclusions plus outer isolation |
| macOS open/osascript fails | Apple Events blocked; review exclusions or allowAppleEvents carefully |
| Nested bubblewrap fails | Consider weaker nested mode only when outer isolation provides the boundary |
| Permission bypass rejected as root | Run as a non-root user in the isolated environment |

## Limits

- Bash isolation does not cover built-in file tools, MCP, or hooks.
- Broad network access increases exfiltration paths.
- Writing PATH entries, shell configuration, or system directories weakens isolation.
- Unix sockets, especially Docker, can bypass intended boundaries.
- Computer use controls the real desktop outside the Bash sandbox.

Prefer containers/VMs for untrusted code. For routine prompt reduction, begin with sandbox auto-allow.

## Official references

- [Sandboxed Bash](https://code.claude.com/en/docs/en/sandboxing.md)
- [Sandbox environments](https://code.claude.com/en/docs/en/sandbox-environments.md)
- [Development containers](https://code.claude.com/en/docs/en/devcontainer.md)

## Related pages



- [Sandbox and dev containers](https://docs.passion8.cc/en/docs/claude-code/sandbox-devcontainers): Containers, VMs, credentials, egress, and cache boundaries.
- [Permissions](https://docs.passion8.cc/en/docs/claude-code/permissions): Rules, automatic mode, and bypass boundaries.
- [Tool reference](https://docs.passion8.cc/en/docs/claude-code/tools): Which tools trigger shell execution or permission checks.
- [Headless automation](https://docs.passion8.cc/en/docs/claude-code/headless): Combine permissions and isolation in scripts and CI.