How to Sandbox Claude Code Securely

To sandbox Claude Code, run /sandbox, enable the built-in Bash sandbox, set it to fail closed, and restrict filesystem, network and credential access. For unattended sessions or untrusted repositories, run the complete Claude Code process inside a container, VM or microVM because the built-in sandbox does not contain file tools, MCP servers or hooks.

Claude Code now includes a Bash sandbox that restricts filesystem and network access. It is a practical default for interactive work. It is not a boundary around the whole Claude Code process: built-in file tools, MCP servers and hooks still run on the host. Anthropic makes that distinction explicit in its sandbox environment comparison.

Claude Code can edit files, run builds, install packages and call external tools. A prompt injection, poisoned dependency or bad command can use that access. This guide separates the controls that reduce that risk from the boundaries that contain the complete agent.

What the Claude Code sandbox protects

The built-in sandbox applies to commands Claude Code runs through its Bash tool and to child processes started by those commands. The operating system enforces two main controls:

• Filesystem rules limit where a command can read and write.
• Network rules limit which domains a command can reach.

On macOS, Claude Code uses Apple's Seatbelt framework. On Linux and WSL2, it uses Bubblewrap for filesystem isolation and a proxy for network policy. Native Windows is not supported; Windows users need WSL2, a container or a VM.

By default, a sandboxed Bash command can write to the working directory and the session's temporary directory. Access to a new network domain requires approval. You can narrow or widen both boundaries in Claude Code settings.

The built-in sandbox covers Bash commands and their child processes, not Claude Code as a whole. Read, Edit and Write tools, MCP servers and hooks remain outside it. Use an outer container, VM or microVM when those components must also be isolated.

How to sandbox Claude Code

Start Claude Code in the project you want to protect and run:

/sandbox

The panel offers two modes:

• Auto-allow runs commands without another prompt when they fit inside the sandbox policy.
• Regular permissions keeps the usual permission prompts while applying the same filesystem and network restrictions.

Choosing a mode writes the project-local preference to .claude/settings.local.json. To enable the sandbox for every project and prevent fallback to unsandboxed execution, add this to ~/.claude/settings.json:

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

Linux and WSL2 require bubblewrap and socat. The /sandbox panel reports missing dependencies. For Ubuntu and Debian, install them with:

sudo apt-get install bubblewrap socat

Before automating a fleet setup, check Anthropic's Bash sandbox documentation for current dependencies, settings and minimum versions.

Make sandbox failure explicit

Claude Code can fall back to unsandboxed execution when the sandbox is unavailable or a command cannot run under its restrictions. Fallback execution may be useful on a developer laptop, but it defeats a deployment that requires sandboxing.

For managed or unattended sessions, keep the fail-closed settings above and test that Claude Code stops when the sandbox cannot start. failIfUnavailable stops Claude Code from starting when sandboxing is enabled but the required boundary cannot start. Setting allowUnsandboxedCommands to false removes the retry path that can run a failed command outside the sandbox.

Keep permission rules as a second control. Explicit deny rules still apply in auto-allow mode, and content-scoped ask rules such as Bash(git push *) can keep sensitive operations behind a prompt. A bare Bash ask rule is skipped for commands that run sandboxed. Permissions decide whether an action may run. Isolation limits what the action can reach after it starts.

Restrict files, network access and credentials

Start with access to the project directory, required build paths and approved network destinations. Do not expose the entire home directory to fix one failing tool.

Claude Code supports filesystem allow and deny rules:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."],
      "allowWrite": ["."]
    },
    "network": {
      "allowedDomains": ["github.com", "registry.npmjs.org"]
    }
  }
}

Put this example in the project's .claude/settings.json. There, . resolves to the project root. The same relative path in user settings resolves under ~/.claude, which produces a different policy.

Credentials need their own rules. A network allowlist does not stop a command from reading a token and sending it to an allowed host. Deny access to credential files and remove unnecessary secrets from the sandboxed environment:

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

Anthropic also supports credential masking on recent Claude Code versions. The command receives a placeholder and the sandbox proxy substitutes the real value only for approved destinations. Masking requires TLS termination, and file masking differs by platform. Configure masking in user or managed settings, or with --settings: Claude Code ignores masking entries in repository settings. Follow Anthropic's current credential-masking documentation rather than copying an old example.

What remains outside the boundary

The built-in Bash sandbox restricts Bash commands, not the complete Claude Code process. It does not isolate:

• Claude Code's built-in file tools
• MCP server processes and the tools they expose
• hooks configured to run alongside Claude Code
• data sent to Anthropic or another configured model provider
• the project files that you deliberately make readable or writable

The last two limits apply to containers and VMs as well. A hypervisor cannot stop an agent from sending readable source code through an allowed connection. Egress policy, credential handling and data governance remain separate controls.

Unattended execution removes the permission prompt that might otherwise catch a dangerous step. Anthropic recommends putting these sessions inside its sandbox runtime, a container or a VM so that the full Claude Code process, including file tools, MCP servers and hooks, sits inside the outer boundary.

Built-in sandbox, container or microVM?

Choose the isolation boundary based on the workload and threat model.

Containers and microVMs can isolate the complete Claude Code process; they differ mainly in whether the workload shares the host kernel. See our Docker sandboxing and microVM comparison for that decision and microVM explainer for the underlying mechanics. Claude Code's Bash sandbox can remain enabled inside either boundary as defense in depth.

Use the AI coding agent sandbox security checklist to compare managed and self-hosted options by isolation, egress, credential handling and persistence.

A secure setup for unattended Claude Code

For an agent that works without a person approving each action, use this sequence:

1. Run the complete Claude Code process inside a dedicated container, VM or microVM.
2. Enable the built-in sandbox as an inner boundary for Bash commands.
3. Fail closed when either boundary is unavailable.
4. Mount only the repository and explicit build paths.
5. Start with deny-default network egress and allow the repository host, package registries and model endpoint as needed.
6. Keep real credentials outside the agent process where possible. Scope and rotate any token the session receives.
7. Treat MCP servers and hooks as code with the agent's privileges. Review them and keep them inside the outer boundary.
8. Destroy the environment after the task and retain an audit trail outside it.

Start with the narrowest usable filesystem and network policy, then add access only when the task requires it.

How ainclave contains Claude Code sessions

For unattended Claude Code sessions, ainclave runs the complete agent process in a dedicated Firecracker microVM. Deny-default egress is enforced outside the guest, and a session can reach only the destinations derived from its selected configuration at create time. Self-service editing of that list is still on the roadmap. Claude Code's built-in sandbox can remain enabled inside the microVM as defense in depth. The controls and current limitations are documented in ainclave's microVM isolation architecture.

Claude Code sandbox checklist

• Run /sandbox and verify that its dependencies are available.
• Decide whether auto-allow or regular permissions matches the task.
• Set failIfUnavailable when sandboxing is mandatory.
• Disable unsandboxed retries for strict deployments.
• Restrict reads, writes and network destinations.
• Deny or mask credentials explicitly.
• Put file tools, MCP servers and hooks inside an outer boundary for unattended work.
• Use a dedicated VM or microVM for untrusted repositories and multi-tenant execution.
• Test the resolved policy before relying on it.

Frequently asked questions

Does Claude Code have a sandbox mode?

Yes. Run /sandbox inside Claude Code to configure its built-in Bash sandbox. It supports auto-allow and regular-permissions modes. Both enforce the same filesystem and network boundary; they differ in whether sandboxed commands require approval.

Is the built-in Claude Code sandbox enough?

It is a good default for interactive Bash commands on trusted projects. It does not contain Claude Code's built-in file tools, MCP servers or hooks. Put the full process inside a sandbox runtime, container or VM for unattended execution.

Can Claude Code run in Docker?

Yes. Run the complete Claude Code process inside a dev container or custom container. For untrusted or multi-tenant workloads, compare its shared-kernel boundary with a VM or microVM before deployment.

Does sandboxing prevent data exfiltration?

Only when readable data and outbound connections are restricted together. A sandbox that allows a process to read a secret and reach an external host still permits exfiltration. Apply filesystem policy, credential controls and deny-default egress as separate layers.

Should I use --dangerously-skip-permissions in a sandbox?

Use it only when the complete Claude Code process runs inside an outer isolation boundary that you have tested. The built-in Bash sandbox alone does not contain file tools, MCP servers or hooks.