Claude Agent SDK Sandbox: How to Configure It in 2026

To configure the Claude Agent SDK sandbox, turn sandboxing on ("sandbox": {"enabled": true} in settings, or /sandbox in Claude Code), pick a permission mode, then narrow what the agent's shell commands can write to and which domains they can reach. The sandbox only covers shell commands, so audit MCP servers and hooks separately, and use a microVM when the agent runs untrusted or generated code.

Sandboxing is off by default. The settings you choose in the first session decide how much of your machine an autonomous agent can reach. Last checked against the Claude Code and Agent SDK docs in October 2026.

#What is the Claude Agent SDK sandbox and why does it matter?

The sandbox is an isolation layer around the shell commands an agent runs. It limits which parts of your filesystem those commands can write to and which network destinations they can reach. Without it, an agent's commands run with the same permissions as the process that launched it.

It addresses three risks. It stops commands from overwriting files outside the paths you allow, such as shell configuration or credentials. It stops outbound calls to hosts you haven't approved, which limits data exfiltration. And it lets you run commands with fewer approval prompts, because each one is already contained.

What the sandbox does not do matters just as much. It covers Bash and the processes it starts. It does not cover the Read, Edit and Write file tools (permission rules govern those), WebFetch and WebSearch, local MCP servers, or command hooks. An agent that reaches your files through an MCP server is not restricted by the sandbox at all.

#How do I turn on the Claude Code sandbox?

Claude Code uses Seatbelt on macOS and bubblewrap on Linux and WSL2. There is no --sandbox flag. Turn it on in one of three ways:

• Run /sandbox inside Claude Code. It saves the setting to .claude/settings.local.json.
• Add it to a settings file, such as .claude/settings.json for the whole project:

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

• Turn it on for a single session:

claude --settings '{"sandbox": {"enabled": true}}'

On macOS, Seatbelt is built in, so there is nothing to install.

On Linux and WSL2, install bubblewrap and socat first:

sudo apt-get install bubblewrap socat   # Debian/Ubuntu
sudo dnf install bubblewrap socat       # Fedora/RHEL

On native Windows, commands are not sandboxed. Run Claude Code inside WSL2 to get bubblewrap-backed isolation.

To confirm it's working, ask the agent to run a command that writes outside the project, such as touch ~/sandbox-test. With the sandbox on, the command should fail with a permission error instead of creating the file.

#How to configure Claude Agent SDK sandbox permissions step by step

With the sandbox on, three settings decide what the agent can actually do.

Step 1: Choose a permission mode. The Agent SDK takes permissionMode in TypeScript and permission_mode in Python. The modes are default, acceptEdits, plan, dontAsk, auto and bypassPermissions. For a new agent, start with default (it asks before acting) or plan (read-only). For a locked-down agent that runs unattended, use dontAsk together with allowedTools, so it can only use the tools you list. Avoid bypassPermissions: allowedTools does not restrict it.

Step 2: Narrow filesystem access. By default, sandboxed commands can write inside the project. Add other paths explicitly instead of widening the whole scope, and deny anything sensitive:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/agent-output"],
      "denyRead": ["~/.ssh", "~/.aws"]
    }
  }
}

Every path you add is one the agent's commands can overwrite without asking. Keep home directories and anything holding credentials out of the list.

Step 3: Allow only the network domains you need. Sandboxed commands reach the network through a proxy outside the sandbox that checks each hostname against your list:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["pypi.org", "registry.npmjs.org"]
    }
  }
}

Tools that ignore proxy settings, such as plain ssh and most database drivers, can't connect at all, and UDP traffic is blocked. If a tool fails after you turn on the sandbox, that's usually why.

In the Agent SDK, the TypeScript SDK accepts the same sandbox settings through its sandbox option. Check the SDK reference for the exact field names in your language before you ship.

#Cloud sandbox providers for the Claude Agent SDK

Cloud sandbox providers give the Claude Agent SDK a remote execution environment, which means your local machine stays out of the blast radius entirely. The tradeoff is that your code and credentials travel to third-party infrastructure.

Four cloud options cover most use cases. The table below compares them across the attributes that matter most for sandbox selection.

Modal uses gVisor to intercept syscalls before they reach the host kernel. GPU acceleration is available, so compute-heavy agent tasks, such as running local model inference alongside code execution, are feasible. The shared-kernel architecture means gVisor's syscall interception is the primary isolation boundary, not a separate kernel per sandbox, per withruntime.com and modal.com.

Vercel Sandbox provisions ephemeral Firecracker microVMs, giving each agent run its own kernel. That is a stronger isolation boundary than a shared-kernel approach. OIDC authentication tokens expire after 12 hours, so long-running agent sessions need token refresh logic. The environment requires Node.js 22 or later, per vercel.com.

Daytona uses containers by default and includes a Secrets system that injects API keys through a secure proxy so the raw key is never visible to the agent process itself, per daytona.io. GPU workloads are supported. If hiding credentials from the agent at the environment level is a priority, Daytona's proxy approach handles that without custom wrapper code.

E2B also runs Firecracker microVMs and is optimized specifically for AI agent code execution. Sessions cap at 24 hours for ephemeral runs, per withruntime.com. Hardware-level isolation per sandbox is the core design choice.

For GPU-dependent workloads, Modal or Daytona are the practical choices. For the strongest per-sandbox kernel isolation at a lower price tier, Vercel Sandbox or E2B fit better. See also the E2B Alternatives That Run Agents in Strict Isolation guide for a deeper look at microVM options beyond this table.

#Can I run Claude agents locally without risking my host filesystem?

Yes. A local microVM or container sandbox puts a hard boundary between the agent and your host filesystem without routing your source code or API keys through any external service. The approach requires more setup than a cloud provider, but it removes the third-party trust problem entirely.

The core requirement is a hypervisor or container runtime that enforces kernel-level separation. Hotcell, our open-source sandbox runtime, is built for this: it runs each agent in its own microVM (Firecracker on Linux, Apple Virtualization on macOS) or container on your own hardware, so the agent's file operations, network calls, and process tree stay inside the sandbox boundary.

The security tradeoff between containers and microVMs matters here. A container shares the host kernel. If the agent exploits a kernel vulnerability, the host is exposed. A microVM, such as one backed by Firecracker, gives the sandbox its own kernel. Exploiting it requires breaking out of the guest kernel first, then the hypervisor layer. For most local development workloads, containers are sufficient. For agents that run untrusted or generated code, a microVM boundary is worth the small overhead.

What a local sandbox prevents, concretely:

• The agent cannot read files outside its mounted working directory.
• Outbound network calls go through a policy layer you define, not the host's default routing.
• A misbehaving agent that fills its disk or exhausts its memory hits the sandbox's resource ceiling, not your host's.
• With Hotcell, the sandbox gets a short-lived token instead of your real API key. A gateway on the host swaps it for the real key on the way out, so a compromised agent has no key to steal.

What it does not prevent: if you mount a directory from your host into the sandbox, the agent can write to that directory. Mount only what the agent needs. The same principle applies to environment variables: pass only the credentials the agent requires for that specific run, not a full copy of your shell environment.

#When a fully local stack makes more sense than a cloud sandbox

Cloud sandboxes are convenient, but three conditions push teams toward a fully local or private-infrastructure stack: data-residency requirements, air-gap constraints, and the need to keep API keys off third-party servers.

Data-residency rules in regulated industries, such as healthcare or financial services, often prohibit sending source code or intermediate outputs to infrastructure outside a specific jurisdiction. A cloud sandbox provider, regardless of its isolation guarantees, still receives your code. A local stack running on your own hardware or a private cloud VM keeps that data inside your control boundary from the first line the agent reads to the last file it writes.

Air-gap requirements are stricter still. Some security environments prohibit any outbound connection during a build or analysis run. A cloud sandbox is structurally incompatible with that constraint. A local microVM stack with a default-deny egress policy satisfies it.

This is what we build at Directionally Local. Autopilot is an open-source terminal coding agent for 25+ model providers or a local model. Hotcell runs its subagents in microVMs or containers with default-deny egress. Both run on a laptop, a Mac mini, a cloud VM or bare metal, and are free under MIT and Apache-2.0.

For teams evaluating the broader space of self-hosted options, the Open-Source Alternatives to Cloud AI Coding Sandboxes guide covers additional tools in this category.

#Checklist before you ship an agent to production

Before moving a Claude agent to production, verify each of these:

1. Sandboxing is on (sandbox.enabled), and the permission mode is default, plan or dontAsk with allowedTools, never bypassPermissions.
2. sandbox.filesystem.allowWrite lists only the extra directories the agent needs, and credentials are in denyRead.
3. sandbox.network.allowedDomains contains only the domains the agent's tasks require.
4. MCP servers, hooks and the file tools have been reviewed separately, since the sandbox does not cover them.
5. A test command confirmed the sandbox blocks a write outside the project.
6. State persistence behavior under a sandbox restart has been tested.

Prices and plan limits verified as of October 2026.

#FAQs

#Which operating systems support the native Claude Code Bash sandbox?

macOS and Linux both support the native Bash sandbox. On macOS, Claude Code uses Seatbelt, which is built into the OS. On Linux and WSL2, it uses bubblewrap, which you install (with socat) through your package manager before turning the sandbox on. Native Windows is not supported: per the Claude Code docs, shell commands run unsandboxed on Windows unless you run Claude Code inside WSL2.

#What happens to agent state if a sandbox container restarts mid-run?

By default, ephemeral containers do not persist state. For long-running agents, keep work in a git branch or a mounted volume so a restart doesn't lose it.

#Is the Claude Agent SDK sandbox compatible with Windows without WSL2?

No. The built-in Bash sandbox relies on Seatbelt (macOS) or bubblewrap (Linux). Neither is available on native Windows. Per code.claude.com, shell commands run without sandbox enforcement on native Windows. If you need isolation on a Windows machine, install WSL2 and run Claude Code from the Linux environment inside it. Cloud sandbox providers such as E2B or Vercel Sandbox are another option, since execution happens on their Linux infrastructure regardless of your local OS.

#How do I allow a specific domain inside the sandbox?

Add it to sandbox.network.allowedDomains in your settings:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["pypi.org"]
    }
  }
}

Start with as few domains as possible and add hosts only when a task needs them.

#What is the difference between container isolation and microVM isolation for Claude agents?

A container shares the host OS kernel. The sandbox boundary is enforced by namespace and cgroup restrictions, but a kernel-level exploit can reach the host. A microVM, such as one backed by Firecracker, runs a separate guest kernel inside a lightweight hypervisor. Breaking out requires compromising the guest kernel and then the hypervisor layer, which is a significantly harder path. For agents running trusted code in a controlled environment, containers are usually sufficient. For agents that execute generated or untrusted code, a microVM boundary reduces the blast radius of a worst-case failure.

#Conclusion

Configuring the sandbox comes down to four choices: turn it on, pick a permission mode, narrow filesystem writes, and allow only the network domains you need. It contains shell commands on macOS, Linux and WSL2, but not the file tools, MCP servers or hooks, so review those separately. For untrusted or generated code, move the agent into a microVM, either with a cloud provider like E2B or Vercel Sandbox or on your own hardware with Hotcell.