Docker Sandboxes for AI Agents

Docker Sandboxes (the sbx command-line tool) runs AI coding agents such as Claude Code, Codex, Copilot, and Gemini inside disposable, isolated micro virtual machines (microVMs). Inside the sandbox the agent has a full Linux machine to do whatever it wants with. Your own computer only exposes the project folder you hand it and the network destinations you allow.

The point is to give an agent real autonomy without handing it your whole computer. It can install packages, run builds, and run tests without asking permission at every step, and it still can't reach your home directory, SSH keys, or cloud credentials.

Before you start
This article covers what Docker Sandboxes are and how to install them. For day-to-day use, see Docker's getting started guide and usage guide. sbx is new and changes quickly between releases, so if a command here doesn't match what you see, trust the official install page and the release notes.

Overview: Docker Sandboxes for AI Agents

How it works

When you run sbx run claude from a project folder, sbx does the following:

• Boots a microVM with its own Linux kernel. It uses the operating system's built-in hypervisor: Hypervisor.framework on macOS, Windows Hypervisor Platform on Windows, and KVM on Linux.
• Mounts your current folder into the VM as the workspace. This folder is the only part of your machine the agent can see.
• Starts a private Docker daemon inside the VM, so the agent can build images and run containers without touching yours.
• Filters outbound network traffic through a policy you choose. The presets are Open, Balanced (deny by default, with common development sites allowed), and Locked Down.
• Handles credentials from the host. For example, Claude Code's login token stays on your machine rather than being stored in the sandbox. See Credentials.

Sandboxes persist after the agent exits. You can stop and resume them, and you delete them when you're done. Everything the agent installed inside the sandbox is discarded at that point, and your project files are left alone. For the details, see Architecture and Isolation layers.

How it compares

	Agent run directly on your machine	Agent in a regular Docker container	Agent in a Docker Sandbox
Isolation boundary	None. The agent runs as you.	Linux namespaces. All containers share one kernel, so escaping the container means reaching the host (or Docker Desktop's VM).	A separate VM with its own kernel for each sandbox.
Files it can touch	Everything your account can read or write, including other repos, ~/.ssh, ~/.aws, and browser profiles.	Whatever you bind-mount. It's easy to mount too much.	Only the workspace folder.
Network	Unrestricted.	Unrestricted by default. Egress filtering is your problem.	Policy-controlled, with presets and per-host allow and deny rules.
Running Docker itself	Uses your Docker daemon.	Requires mounting the host's Docker socket, which is effectively root on the host.	Uses its own daemon inside the VM. Nothing is shared with the host.
Setup	None.	You write and maintain the Dockerfile, mounts, and agent install.	One command. The common agents come preinstalled.

Compared with running an agent directly on your machine: coding agents protect you mostly by asking permission before running commands. After the fiftieth prompt, most people either click "approve" without reading or turn the prompts off entirely. Inside a sandbox, turning prompts off is much less dangerous. A bad command, a hallucinated rm -rf, or a prompt injection hidden in a README or web page can only reach the workspace and the network hosts you allowed.

Compared with plain Docker: you can build your own agent container. To make it safe, though, you have to solve the problems Sandboxes already handle. You need a kernel boundary rather than a shared kernel, outbound filtering, a way to keep API keys out of the container, and a way for the agent to use Docker without mounting the host socket. Sandboxes also don't require Docker Desktop. You may see a docker sandbox command that ships with Docker Desktop. This article uses the standalone sbx CLI instead.

Warning: What a sandbox does not protect

• Your workspace. By default the project folder is mounted read-write, so the agent can still delete or break files in it. Commit before you start, or use clone mode to give the agent a private copy.
• What the agent sends to the model. The sandbox limits what the agent can touch. It does not limit what gets sent to the model provider's API as context. Don't put data you aren't permitted to share with a third party (for example, restricted or IRB-protected data) in the workspace.
• Hosts you allow. The Open policy, or broad allow rules, can still be used to move data out of the sandbox. Tokens you give the agent, such as a GitHub token, can be used for anything they're scoped for.

See Security defaults for exactly what is and isn't allowed out of the box.

Installing on Windows

Requirements: Windows 11 on a 64-bit Intel or AMD processor (Windows on Arm is not supported), hardware virtualization turned on, and administrator rights once to enable Windows Hypervisor Platform. Run all commands in PowerShell. Steps marked (Administrator) need an elevated prompt: right-click PowerShell and choose Run as administrator.

Step 1: Check your system

# Should print "Microsoft Windows 11 ..."
(Get-CimInstance Win32_OperatingSystem).Caption

# Should print AMD64
$env:PROCESSOR_ARCHITECTURE

Next, open Task Manager → Performance → CPU and check that it shows Virtualization: Enabled. If it shows Disabled, turn on Intel VT-x or AMD-V (SVM) in your BIOS/UEFI settings. Microsoft's guide covers this: Enable virtualization on Windows.

Step 2: Enable Windows Hypervisor Platform (Administrator)

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
Restart-Computer

After rebooting, check that the feature is on. It should report Enabled:

(Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform).State

If you're on a department-managed laptop without admin rights, this is the one step you'll need IT for.

Step 3: Install sbx

In a regular (non-admin) PowerShell window:

winget install -h Docker.sbx

This installs sbx for your user only, in %LOCALAPPDATA%\DockerSandboxes, and adds it to your user PATH. Close and reopen PowerShell, then confirm that it works:

sbx version

If you get sbx is not recognized, the PATH change hasn't been picked up yet. Open a new window, or sign out and back in. You can confirm the binary exists with Test-Path "$env:LOCALAPPDATA\DockerSandboxes\bin\sbx.exe".

To install for every user on a shared machine, use the machine-wide MSI described on the install page.

Step 4: Sign in

sbx login

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at Docker Hub. The FAQ explains why sign-in is required.

Step 5: Run your first sandbox

cd $HOME\path\to\your-project
git status        # commit or stash anything you care about first
sbx run claude

The first time you run a sandbox, sbx asks you to choose a default network policy. Balanced is a sensible starting point. The first run also takes a minute while the agent image downloads. For Claude Code with a Claude subscription, type /login inside the sandbox. For other agents or API keys, see the agent pages.

Updating later: winget upgrade Docker.sbx

Installing on macOS

Requirements: a Mac with Apple silicon (M1 or later) running macOS 14 Sonoma or later. Intel Macs are not supported. You also need Homebrew. Run all commands in Terminal.

Step 1: Check your system

uname -m                  # should print arm64
sw_vers -productVersion   # should be 14.0 or higher
brew --version            # if this fails, install Homebrew from https://brew.sh

Step 2: Install sbx

brew trust docker/tap
brew install docker/tap/sbx

The first command marks Docker's Homebrew tap as trusted. If Homebrew reports brew trust as an unknown command, run brew update and try again.

Confirm the install:

sbx version

Step 3: Sign in

sbx login

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at Docker Hub. The FAQ explains why sign-in is required.

Step 4: Run your first sandbox

cd ~/path/to/your-project
git status        # commit or stash anything you care about first
sbx run claude

The first time you run a sandbox, sbx asks you to choose a default network policy. Balanced is a sensible starting point. For Claude Code with a Claude subscription, type /login inside the sandbox. For other agents or API keys, see the agent pages.

Updating later: brew upgrade docker/tap/sbx

Installing on Linux

Requirements: Ubuntu 24.04 or later on x86-64 or 64-bit Arm, KVM hardware virtualization, and sudo. Docker does not support Ubuntu derivatives such as Linux Mint or Pop!_OS, because the install script can configure the wrong package repository on them. For other distributions, see the release artifacts, which Docker does not test. If you're installing inside a virtual machine, the VM must support nested virtualization.

Shared servers and clusters
Installing sbx needs sudo and membership in the kvm group, which you usually won't have on department compute servers or clusters. Run sandboxes on your own machine, or ask the system administrators.

Step 1: Check your system

lsb_release -ds    # should be Ubuntu 24.04 or later
uname -m           # x86_64 or aarch64
lsmod | grep kvm   # should list kvm_intel, kvm_amd, kvm_arm64, or kvm

If the last command prints nothing, find out why with:

sudo apt install cpu-checker
kvm-ok

The usual cause is that virtualization is turned off in the BIOS/UEFI.

Step 2: Add yourself to the kvm group

sudo usermod -aG kvm $USER
newgrp kvm                 # or log out and back in
groups | grep -w kvm       # should now print your groups, including kvm

Step 3: Install sbx

Choose one of the following options.

Option A: sbx only. Choose this if you don't need Docker Engine on the host.

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh   # adds Docker's apt repository
sudo apt install docker-sbx

Option B: Docker Engine and sbx together.

curl -fsSL https://get.docker.com | sudo SBX=1 sh

If you'd rather read the install script before running it with root privileges, download it first:

curl -fsSL https://get.docker.com -o get-docker.sh
less get-docker.sh
sudo REPO_ONLY=1 sh get-docker.sh   # or SBX=1 for Option B

Confirm the install:

sbx version

Step 4: Sign in

sbx login

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at Docker Hub. On a machine without a desktop, see Troubleshooting.

Step 5: Run your first sandbox

cd ~/path/to/your-project
git status        # commit or stash anything you care about first
sbx run claude

The first time you run a sandbox, sbx asks you to choose a default network policy. Balanced is a sensible starting point. For Claude Code with a Claude subscription, type /login inside the sandbox. For other agents or API keys, see the agent pages.

Updating later: sudo apt update && sudo apt install --only-upgrade docker-sbx

Next steps: Once your first sandbox runs, read the usage guide for reconnecting, ports, and clone mode. The Git workflows page covers letting agents push branches, Local policy covers tuning network rules, and the CLI reference lists every command.