View source for Docker Sandboxes for AI Agents

<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->
[[Category:AI Tools]]
[[Category:Containers and Virtual Environments]]

'''[https://docs.docker.com/ai/sandboxes/ Docker Sandboxes]''' (the <code>sbx</code> 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.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Before you start'''<br>
This article covers what Docker Sandboxes are and how to install them. For day-to-day use, see Docker's [https://docs.docker.com/ai/sandboxes/get-started/ getting started guide] and [https://docs.docker.com/ai/sandboxes/usage/ usage guide]. <code>sbx</code> is new and changes quickly between releases, so if a command here doesn't match what you see, trust the [https://docs.docker.com/ai/sandboxes/install/ official install page] and the [https://docs.docker.com/ai/sandboxes/release-notes/ release notes].
</div>

== Overview: Docker Sandboxes for AI Agents ==

=== How it works ===
When you run <code>sbx run claude</code> from a project folder, <code>sbx</code> 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 [https://docs.docker.com/ai/sandboxes/configuration/credentials/ 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 [https://docs.docker.com/ai/sandboxes/architecture/ Architecture] and [https://docs.docker.com/ai/sandboxes/security/isolation/ Isolation layers].

=== How it compares ===
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 16%; background-color: #e9ecef; padding: 10px; text-align: left;" |
! style="width: 28%; background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Agent run directly on your machine
! style="width: 28%; background-color: #fff3cd; color: #856404; padding: 10px; text-align: left;" | Agent in a regular Docker container
! style="width: 28%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | Agent in a Docker Sandbox
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Isolation boundary'''
| style="padding: 10px;" | None. The agent runs as ''you''.
| style="padding: 10px;" | Linux namespaces. All containers share one kernel, so escaping the container means reaching the host (or Docker Desktop's VM).
| style="padding: 10px;" | A separate VM with its own kernel for each sandbox.
|- style="vertical-align: top; background-color: #ffffff;"
| style="padding: 10px;" | '''Files it can touch'''
| style="padding: 10px;" | Everything your account can read or write, including other repos, <code>~/.ssh</code>, <code>~/.aws</code>, and browser profiles.
| style="padding: 10px;" | Whatever you bind-mount. It's easy to mount too much.
| style="padding: 10px;" | Only the workspace folder.
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Network'''
| style="padding: 10px;" | Unrestricted.
| style="padding: 10px;" | Unrestricted by default. Egress filtering is your problem.
| style="padding: 10px;" | Policy-controlled, with presets and per-host allow and deny rules.
|- style="vertical-align: top; background-color: #ffffff;"
| style="padding: 10px;" | '''Running Docker itself'''
| style="padding: 10px;" | Uses your Docker daemon.
| style="padding: 10px;" | Requires mounting the host's Docker socket, which is effectively root on the host.
| style="padding: 10px;" | Uses its own daemon inside the VM. Nothing is shared with the host.
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Setup'''
| style="padding: 10px;" | None.
| style="padding: 10px;" | You write and maintain the Dockerfile, mounts, and agent install.
| style="padding: 10px;" | 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 <code>rm -rf</code>, 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 <code>docker sandbox</code> command that ships with Docker Desktop. This article uses the standalone <code>sbx</code> CLI instead.

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Warning: What a sandbox does ''not'' protect'''<br>
* '''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 [https://docs.docker.com/ai/sandboxes/usage/ 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.
</div>

See [https://docs.docker.com/ai/sandboxes/security/defaults/ Security defaults] for exactly what is and isn't allowed out of the box.

== Installing on Windows ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''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''.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="powershell">
# Should print "Microsoft Windows 11 ..."
(Get-CimInstance Win32_OperatingSystem).Caption

# Should print AMD64
$env:PROCESSOR_ARCHITECTURE
</syntaxhighlight>

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: [https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1 Enable virtualization on Windows].

=== Step 2: Enable Windows Hypervisor Platform (Administrator) ===
<syntaxhighlight lang="powershell">
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
Restart-Computer
</syntaxhighlight>

After rebooting, check that the feature is on. It should report <code>Enabled</code>:
<syntaxhighlight lang="powershell">
(Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform).State
</syntaxhighlight>

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:
<syntaxhighlight lang="powershell">
winget install -h Docker.sbx
</syntaxhighlight>

This installs <code>sbx</code> for your user only, in <code>%LOCALAPPDATA%\DockerSandboxes</code>, and adds it to your user <code>PATH</code>. '''Close and reopen PowerShell''', then confirm that it works:
<syntaxhighlight lang="powershell">
sbx version
</syntaxhighlight>

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

To install for every user on a shared machine, use the machine-wide MSI described on the [https://docs.docker.com/ai/sandboxes/install/ install page].

=== Step 4: Sign in ===
<syntaxhighlight lang="powershell">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. The [https://docs.docker.com/ai/sandboxes/faq/ FAQ] explains why sign-in is required.

=== Step 5: Run your first sandbox ===
<syntaxhighlight lang="powershell">
cd $HOME\path\to\your-project
git status        # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> 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 <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>winget upgrade Docker.sbx</code>

== Installing on macOS ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Requirements:''' a Mac with Apple silicon (M1 or later) running macOS 14 Sonoma or later. Intel Macs are not supported. You also need [https://brew.sh Homebrew]. Run all commands in Terminal.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

=== Step 2: Install sbx ===
<syntaxhighlight lang="bash">
brew trust docker/tap
brew install docker/tap/sbx
</syntaxhighlight>

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

Confirm the install:
<syntaxhighlight lang="bash">
sbx version
</syntaxhighlight>

=== Step 3: Sign in ===
<syntaxhighlight lang="bash">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. The [https://docs.docker.com/ai/sandboxes/faq/ FAQ] explains why sign-in is required.

=== Step 4: Run your first sandbox ===
<syntaxhighlight lang="bash">
cd ~/path/to/your-project
git status        # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> asks you to choose a default network policy. '''Balanced''' is a sensible starting point. For Claude Code with a Claude subscription, type <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>brew upgrade docker/tap/sbx</code>

== Installing on Linux ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Requirements:''' Ubuntu 24.04 or later on x86-64 or 64-bit Arm, KVM hardware virtualization, and <code>sudo</code>. 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 [https://github.com/docker/sbx-releases#manual-install-from-release-artifacts release artifacts], which Docker does not test. If you're installing inside a virtual machine, the VM must support nested virtualization.
</div>

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Shared servers and clusters'''<br>
Installing <code>sbx</code> needs <code>sudo</code> and membership in the <code>kvm</code> group, which you usually won't have on department compute servers or clusters. Run sandboxes on your own machine, or ask the system administrators.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

If the last command prints nothing, find out why with:
<syntaxhighlight lang="bash">
sudo apt install cpu-checker
kvm-ok
</syntaxhighlight>

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

=== Step 2: Add yourself to the kvm group ===
<syntaxhighlight lang="bash">
sudo usermod -aG kvm $USER
newgrp kvm                 # or log out and back in
groups | grep -w kvm       # should now print your groups, including kvm
</syntaxhighlight>

=== Step 3: Install sbx ===
Choose '''one''' of the following options.

'''Option A: <code>sbx</code> only.''' Choose this if you don't need Docker Engine on the host.
<syntaxhighlight lang="bash">
curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh   # adds Docker's apt repository
sudo apt install docker-sbx
</syntaxhighlight>

'''Option B: Docker Engine and <code>sbx</code> together.'''
<syntaxhighlight lang="bash">
curl -fsSL https://get.docker.com | sudo SBX=1 sh
</syntaxhighlight>

If you'd rather read the install script before running it with root privileges, download it first:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Confirm the install:
<syntaxhighlight lang="bash">
sbx version
</syntaxhighlight>

=== Step 4: Sign in ===
<syntaxhighlight lang="bash">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. On a machine without a desktop, see [https://docs.docker.com/ai/sandboxes/troubleshooting/ Troubleshooting].

=== Step 5: Run your first sandbox ===
<syntaxhighlight lang="bash">
cd ~/path/to/your-project
git status        # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> asks you to choose a default network policy. '''Balanced''' is a sensible starting point. For Claude Code with a Claude subscription, type <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>sudo apt update && sudo apt install --only-upgrade docker-sbx</code>

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Next steps:''' Once your first sandbox runs, read the [https://docs.docker.com/ai/sandboxes/usage/ usage guide] for reconnecting, ports, and clone mode. The [https://docs.docker.com/ai/sandboxes/workflows/git/ Git workflows] page covers letting agents push branches, [https://docs.docker.com/ai/sandboxes/governance/access-controls/local/ Local policy] covers tuning network rules, and the [https://docs.docker.com/reference/cli/sbx/ CLI reference] lists every command.
</div>