Claude Code

Sandboxing and isolation

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

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

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

sudo apt-get install bubblewrap socat

Fedora:

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:

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

Allow selected write directories:

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

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

{
  "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:

{
  "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:

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

#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.