| Reading time: | 10 min |
| Last updated: | 17 Jun 2026 |
| Reading time: |
| 10 min |
| Last updated: |
| 17 Jun 2026 |
This guide shows you how to install and use the tool with the most common configuration. For advanced options and complete reference information, see the official documentation. Some install guides also include optional next steps to help you explore related workflows or integrations.
Docker Sandboxes (sbx) is a standalone CLI from Docker for running AI coding agents in isolated microVMs. Each sandbox gets its own filesystem, network, and Docker daemon, so agents can install packages, modify files, and run containers without touching your host system.
Arm Linux support is available in sbx version 0.33 and later.
On macOS with Apple Silicon, sbx uses Apple’s virtualization framework to launch Arm Linux (Ubuntu) microVMs. You don’t need Docker Desktop.
On Arm Linux, sbx uses the KVM hypervisor to launch microVMs. KVM requires bare metal and does not work on virtual machines.
You need:
sbx.You need:
sbx.Install sbx using Homebrew:
brew install docker/tap/sbx
Homebrew installs the sbx binary at /opt/homebrew/bin/sbx.
On Arm Linux, sbx requires KVM acceleration. KVM does not typically work on virtual machines. It requires bare metal.
Install and run the kvm-ok command to confirm KVM is available.
Install kvm-ok on Debian-based Linux distributions:
sudo apt install cpu-checker -y
To check if KVM is available, run:
sudo kvm-ok
If KVM is available, the output is similar to:
INFO: /dev/kvm exists
KVM acceleration can be used
If KVM is not available, the output is similar to:
INFO: /dev/kvm does not exist
HINT: sudo modprobe kvm
INFO: For more detailed results, you should run this as root
HINT: sudo /usr/sbin/kvm-ok
After KVM is available, install sbx using the appropriate .deb package for your Ubuntu version. First, check your Ubuntu version:
grep VERSION_ID /etc/os-release
The following commands use Docker Sandboxes version 0.33.0. The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest release and available Ubuntu versions, see the sbx releases page .
For Ubuntu 26.04, download and install the .deb package:
wget https://github.com/docker/sbx-releases/releases/download/v0.33.0/DockerSandboxes-linux-arm64-ubuntu2604.deb
sudo apt install ./DockerSandboxes-linux-arm64-ubuntu2604.deb
For Ubuntu 24.04, download and install the .deb package:
wget https://github.com/docker/sbx-releases/releases/download/v0.33.0/DockerSandboxes-linux-arm64-ubuntu2404.deb
sudo apt install ./DockerSandboxes-linux-arm64-ubuntu2404.deb
Verify the installation:
which sbx
The output is similar to:
/usr/bin/sbx
After installing the CLI, verify that the installation was successful.
Start by checking what version of sbx is installed:
sbx version
The following output shows the version at the time this guide was written. To find the latest release, see the sbx releases page .
The output is similar to:
sbx version: v0.33.0 d7da69cb30eb3000c4d4ef0c848ffe84f32058bf
Sign in to your Docker account:
sbx login
This outputs a one-time code and a URL. Open the link in a browser, sign in with your Docker Hub credentials, and approve the activation.
Navigate to your project directory and start an agentless sandbox for manual exploration:
sbx run shell
This launches a bare Arm Linux microVM with a shell prompt. No AI agent runs inside it.
On your first run, the CLI will ask you to select a network policy:
Open: allows all network access from within the sandbox.Balanced: allows common development services while blocking everything else.Locked Down: blocks all outbound network traffic.Balanced is a good starting point for most development workflows.
To ensure the shell sandbox runs as expected, from within the sandbox, verify the operating system and architecture:
uname -a
The output is similar to:
Linux shell-arm-learning-paths 7.0.8 #1 SMP PREEMPT Thu Jun 4 20:59:42 UTC 2026 aarch64 GNU/Linux
Check the Ubuntu release:
cat /etc/os-release
The output is similar to:
PRETTY_NAME="Ubuntu 26.04 LTS"
NAME="Ubuntu"
VERSION_ID="26.04"
VERSION="26.04 (Resolute Raccoon)"
VERSION_CODENAME=resolute
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=resolute
LOGO=ubuntu-logo
This confirms that the shell sandbox is running Arm Linux (Ubuntu on aarch64) inside the microVM.
Keep the shell running to test management commands in another terminal.
In another terminal window, list all sandboxes with their agent and current status:
sbx ls
The output is similar to:
SANDBOX AGENT STATUS PORTS WORKSPACE
shell-arm-learning-paths shell stopped ~/my-project
Copy a file from your host into the sandbox. For example:
sbx cp ./myfile.txt <SANDBOX>:/home/user/myfile.txt
Copy a file from a sandbox back to your host. For example:
sbx cp <SANDBOX>:/home/user/output.txt ./output.txt
Stop the running shell sandbox using its name:
sbx stop <SANDBOX>
The running shell sandbox in the first terminal window stops.
Remove the sandbox permanently:
sbx rm <SANDBOX>
You’ll be prompted to confirm whether you want to remove the sandbox. Answer y and press Enter to delete the sandbox.
You’re now ready to use Docker Sandboxes to run AI agents in isolated microVMs on macOS or Arm Linux.
To launch an agent sandbox, provide the name of the agent sandbox in the run command. For example, to launch a Claude sandbox:
sbx run claude
Other supported agent sandboxes include copilot, codex, and kiro. For the full list, see the
Docker Sandboxes agents documentation
.
You can use AI agents with the Arm MCP Server to build on or migrate to Arm. For more information, see the Arm MCP Server Learning Path.
How would you rate this tool quick-install guide?
What is the primary reason for your feedback ?
Thank you! We're grateful for your feedback.