Docker sbx: stop running Claude Code without a sandbox

Claude Code is one of the most popular AI agents. It can write, test and run code on its own. That is exactly what makes it powerful, and exactly what creates a serious security problem: without isolation, it runs with the same privileges as you on your system. Your SSH keys, your AWS tokens, your .env files, your Docker daemon: everything is within the agent’s reach. Docker sbx, Docker’s sandboxing tool, lets you easily lock the agent inside a dedicated microVM. This article explains why this precaution matters and how to set it up in a few minutes.

What Claude Code can reach without isolation

When you run Claude Code on your machine without a sandbox, the agent process inherits your entire shell session. It has full access to your home directory, to your exported environment variables (including AWS_SECRET_ACCESS_KEY, DATABASE_URL or any token stored in your shell), to your SSH keys in ~/.ssh, to the .env files scattered across your projects, and to the host’s Docker daemon, which can open a path to production environments.

The agent doesn’t need to be malicious for something to go wrong. A compromised npm package in a dependency, a prompt injection in a file the agent reads, or a misconfigured MCP server is enough to hijack the tool’s behaviour without you noticing.

Documented incidents, not theoretical scenarios

Several incidents illustrate this risk. The s1ngularity supply chain attack used Claude Code as a data exfiltration tool. The Cline extension (more than five million users) suffered a prompt injection that led to npm tokens being exfiltrated. The Comment and Control technique, presented at BSides San Francisco 2026, showed how AI agents wired into code review tools on GitHub Actions, including Claude Code Security Review, could be hijacked through carefully crafted pull request comments.

Claude Code’s own native network sandbox has suffered two serious bypasses since its general availability launch in October 2025. CVE-2025-66479: an empty allowlist, allowedDomains: [], meant to block all outbound traffic, was interpreted as “allow everything”. The second issue, a null-byte injection in the SOCKS5 proxy, made it possible to bypass any allowlist with a single \x00 character. Both flaws were fixed silently, with no published security advisory and no user notification. The fixes shipped in November 2025 (v2.0.55) and April 2026 (v2.1.90) respectively.

These incidents highlight a structural point: operating-system-level isolation, however well configured, remains vulnerable to software bypasses. Kernel-level isolation addresses this threat differently.

Docker sbx: a microVM, not just a container

Docker sbx is a standalone CLI tool (it doesn’t require Docker Desktop) that runs AI agents in lightweight microVMs. The difference with a regular Docker container matters for security: a container shares the host’s kernel, so a container escape gives access to the host kernel. A microVM has its own isolated Linux kernel, so a potential escape leads to nothing exploitable on the host (see * for purists).

*A microVM has its own isolated Linux kernel. A potential escape would have to target the hypervisor (KVM on Linux, Apple Virtualization Framework on macOS), a much smaller attack surface, separate from the host system.

In practice, with sbx, Claude Code runs entirely inside the VM. Only the working directory you explicitly mount is shared between the VM and your system. Outbound network traffic must go through a host proxy with a configurable policy. Your credentials (Anthropic API key, cloud tokens) are managed on the host through the system keychain and injected at the proxy level: the agent never sees the raw values.

This is also why Claude Code’s --dangerously-skip-permissions option is the default mode in sbx: the sandbox is the security boundary, so manual confirmations become redundant. That is precisely the point of the product: you give the agent full autonomy inside a perimeter you control.

Installing Docker sbx

Docker sbx currently supports macOS (Apple Silicon, M1 or later, macOS Sonoma 14 minimum), Windows, and Linux Ubuntu 24.04 or later (x86_64 and aarch64 architectures) with KVM virtualisation.

A Docker Hub account is required for authentication. Individual use is free. Centralised administration features (team network policies, filesystem control at scale) require contacting Docker directly through their dedicated form.

Installing on macOS (Apple Silicon)

brew install docker/tap/sbx
sbx login

The sbx login command opens an OAuth flow in your browser. You only need to authenticate once.

Installing on Windows

winget install Docker.sbx
sbx login

Installing on Linux (Ubuntu, x86_64 or aarch64)

On Linux, sbx relies on KVM for virtualisation. KVM must be available on bare-metal hardware (it doesn’t work inside a VM). Check that it is available with:

lsmod | grep kvm

If the output is empty, run kvm-ok to diagnose. If KVM is available, add your user to the relevant group, then install sbx:

sudo usermod -aG kvm $USER
# Log out and back in for the group change to take effect

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sbx login

Running Claude Code in the sandbox

The basic command is simple: go to your project directory and run:

cd ~/my-project
sbx run claude .

The final dot indicates the working directory to mount in the VM. On first launch, the agent image is downloaded (one to two minutes). Subsequent runs reuse the cached image and start in a few seconds.

If you use Claude Code with an Anthropic API key, export it before launching and store it in the sbx keychain:

echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic

With a Claude subscription (Max, Team or Enterprise), no key is needed: use the /login command inside the sandboxed session to authenticate via OAuth. The proxy handles the flow, and your credentials never travel in clear text inside the VM.

One thing to know before configuring your first sandbox: it doesn’t pick up your usual user configuration (the ~/.claude folder on your machine). Only project-level configuration, in the mounted working directory, is taken into account. If you have custom user-level settings (output styles, global preferences), you will need to redefine them at project level for them to apply in the sandbox.

To name a sandbox and reuse it across sessions (configurations persist):

sbx run --name my-project claude .

Run sbx without arguments to open the interactive dashboard: it shows the state of each sandbox, live CPU and memory usage, and the network panel (Tab key), which lists in real time every outbound connection the agent attempts, allowed or blocked.

Configuring the network policy

On first launch, sbx asks you to choose a default network policy. Three options are available:

• Open: all outbound traffic is allowed, with no restrictions.
• Balanced: deny by default, with common development services pre-allowed (package registries, common CDNs). This is the right starting point for most projects.
• Locked Down: all traffic is blocked, including the Anthropic API, unless explicitly added to the allowlist.

The Balanced policy is recommended for everyday use. If the agent needs to reach a service not covered by the default policy (an external API, a private registry), you can allow it explicitly with sbx policy:

sbx policy allow network api.myservice.com

For a project with precise, reproducible network needs, define these rules in a YAML kit file versioned alongside your code. The sandbox is then configured automatically on creation, including installation of the required system dependencies.

Claude Code’s native sandbox, an alternative

If KVM isn’t available on your machine (a VM without nested virtualisation, for example), Claude Code offers a native sandbox you can enable with the /sandbox command inside a session, built on bubblewrap (Linux) or macOS Seatbelt.

This approach restricts writes to the current directory and filters network traffic through a proxy. But it has an important structural difference from sbx: Claude Code keeps running as a process of your host user, on your machine’s kernel. The restrictions are enforced by the operating system and can be bypassed through a kernel vulnerability or a flaw in the implementation (two bypasses have in fact been documented in Claude Code’s native network sandbox, described above). With sbx, the VM’s kernel is the isolation boundary, and an attack escaping that perimeter gains no host access.

On Linux x86_64, the native sandbox remains a valid layer of defence if sbx isn’t an option. Install bubblewrap and socat first, then enable the sandbox with /sandbox in Claude Code and, if you manage configuration programmatically, make sure allowUnsandboxedCommands: false is set so that a sufficiently motivated agent can’t disable it itself.

The go-to external reference on this topic is Anthropic’s engineering post: Making Claude Code more secure and autonomous with sandboxing.

The Claude Code base image and custom templates

By default, sbx run claude uses the docker/sandbox-templates:claude-code-docker image. The suffix matters: it ships a full Docker Engine inside the microVM itself, running in privileged mode. In practice, the agent can build and run its own containers without ever touching your host’s Docker daemon: isolation stays intact, while the agent keeps all the latitude it needs for realistic development workflows.

If you don’t need Docker inside the sandbox, the lighter variant is preferable to reduce both the attack surface and the image size:

sbx run claude –template docker.io/docker/sandbox-templates:claude-code

For a team that always repeats the same setup (same tools, same system dependencies), you can build a custom template from a Dockerfile that extends the base image, or save the state of an existing sandbox with sbx template save. One limitation to know before relying on it: the agent’s user configuration files (~/.claude/settings.json, ~/.claude.json) are always recreated at startup and never persist in a saved template, even if you modified them in the source sandbox. Only installed packages and files outside that scope are kept.

Docker sbx cheatsheet

Getting started

Command	Description
sbx run claude .	Run Claude Code in the current directory
sbx run --name my-project claude .	Run with a persistent name (configuration kept across sessions)
sbx run claude -- --continue	Resume the previous Claude Code session
sbx run --clone --name my-project claude .	Isolated clone of the repository, host mounted read-only

Managing sandboxes

Command	Description
sbx ls	List existing sandboxes
sbx rm my-project	Delete a sandbox
sbx exec -it my-project bash	Open an interactive shell in the sandbox
sbx	Open the TUI dashboard (live state, CPU, memory, network)

Credentials

Command	Description
echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic	Store the API key from an environment variable (nothing in shell history)
sbx secret set -g anthropic < ~/.secrets/key	Store the key from a file
sbx secret list	List secrets stored in the keychain

Network

Command	Description
sbx policy allow network api.myservice.com	Allow a domain in the network policy
sbx policy reset	Reset the network policy (asks again for Open / Balanced / Locked Down)
sbx ports my-project --publish 3000:3000/tcp	Expose a sandbox port to the host

Claude Code sandbox and Docker sbx FAQ