|
| 1 | +--- |
| 2 | +title: Docker Sandboxes (sbx) |
| 3 | + |
| 4 | +description: Install Docker Sandboxes (sbx) on macOS with Apple Silicon to run AI coding agents in isolated Arm Linux microVMs using Apple's virtualization framework. |
| 5 | + |
| 6 | +minutes_to_complete: 10 |
| 7 | + |
| 8 | +official_docs: https://docs.docker.com/ai/sandboxes/ |
| 9 | + |
| 10 | +additional_search_terms: |
| 11 | +- docker |
| 12 | +- sbx |
| 13 | +- sandbox |
| 14 | +- microvm |
| 15 | +- containers |
| 16 | +- apple silicon |
| 17 | + |
| 18 | +author: Jason Andrews |
| 19 | + |
| 20 | +test_images: |
| 21 | +test_maintenance: false |
| 22 | + |
| 23 | +weight: 1 |
| 24 | +tool_install: true |
| 25 | +multi_install: false |
| 26 | +multitool_install_part: false |
| 27 | +layout: installtoolsall |
| 28 | +--- |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +{{% notice Note %}} |
| 33 | +`sbx` is not available on Arm Linux. |
| 34 | +{{% /notice %}} |
| 35 | + |
| 36 | +On macOS with Apple Silicon, `sbx` uses Apple's virtualization framework to launch Arm Linux (Ubuntu) microVMs. You don't need Docker Desktop. |
| 37 | + |
| 38 | +## Before you begin |
| 39 | + |
| 40 | +You need: |
| 41 | + |
| 42 | +- A Mac with Apple Silicon (M1 or later) running macOS Sonoma (version 14) or later. |
| 43 | +- A [Docker Hub](https://hub.docker.com/) account to authenticate `sbx`. |
| 44 | +- [Homebrew](https://brew.sh/) installed. |
| 45 | + |
| 46 | +## Install the sbx CLI |
| 47 | + |
| 48 | +Install `sbx` using Homebrew: |
| 49 | + |
| 50 | +```bash |
| 51 | +brew install docker/tap/sbx |
| 52 | +``` |
| 53 | + |
| 54 | +Homebrew installs the `sbx` binary at `/opt/homebrew/bin/sbx`. |
| 55 | + |
| 56 | +## Verify the installation |
| 57 | + |
| 58 | +After installing the CLI, verify that the installation was successful. |
| 59 | + |
| 60 | +### Check the sbx CLI version |
| 61 | + |
| 62 | +Start by checking what version of `sbx` is installed: |
| 63 | + |
| 64 | +```bash |
| 65 | +sbx version |
| 66 | +``` |
| 67 | + |
| 68 | +{{% notice Note %}} |
| 69 | +The following output shows the version at the time this guide was written. Homebrew installs the latest available version. To find the latest release, see the [sbx releases page](https://github.com/docker/sbx-releases/releases). |
| 70 | +{{% /notice %}} |
| 71 | + |
| 72 | +The output is similar to: |
| 73 | + |
| 74 | +```output |
| 75 | +sbx version: v0.32.0 55580366449bcfebfc1787b9944284cf64c856d7 |
| 76 | +``` |
| 77 | + |
| 78 | +### Authenticate with Docker Hub |
| 79 | + |
| 80 | +Sign in to your Docker account: |
| 81 | + |
| 82 | +```bash |
| 83 | +sbx login |
| 84 | +``` |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +### Start a shell sandbox |
| 89 | + |
| 90 | +Navigate to your project directory and start an agentless sandbox for manual exploration: |
| 91 | + |
| 92 | +```bash |
| 93 | +sbx run shell |
| 94 | +``` |
| 95 | + |
| 96 | +This launches a bare Arm Linux microVM with a shell prompt. No AI agent runs inside it. |
| 97 | +On your first run, the CLI will ask you to select a network policy: |
| 98 | + |
| 99 | +- `Open`: allows all network access from within the sandbox. |
| 100 | +- `Balanced`: allows common development services while blocking everything else. |
| 101 | +- `Locked Down`: blocks all outbound network traffic. |
| 102 | + |
| 103 | +`Balanced` is a good starting point for most development workflows. |
| 104 | + |
| 105 | +### Confirm the sandbox runs Arm Linux |
| 106 | + |
| 107 | +To ensure the shell sandbox runs as expected, from within the sandbox, verify the operating system and architecture: |
| 108 | + |
| 109 | +```bash |
| 110 | +uname -a |
| 111 | +``` |
| 112 | + |
| 113 | +The output is similar to: |
| 114 | + |
| 115 | +```output |
| 116 | +Linux shell-arm-learning-paths 7.0.8 #1 SMP PREEMPT Thu Jun 4 20:59:42 UTC 2026 aarch64 GNU/Linux |
| 117 | +``` |
| 118 | + |
| 119 | +Check the Ubuntu release: |
| 120 | + |
| 121 | +```bash |
| 122 | +cat /etc/os-release |
| 123 | +``` |
| 124 | + |
| 125 | +The output is similar to: |
| 126 | + |
| 127 | +```output |
| 128 | +PRETTY_NAME="Ubuntu 26.04 LTS" |
| 129 | +NAME="Ubuntu" |
| 130 | +VERSION_ID="26.04" |
| 131 | +VERSION="26.04 (Resolute Raccoon)" |
| 132 | +VERSION_CODENAME=resolute |
| 133 | +ID=ubuntu |
| 134 | +ID_LIKE=debian |
| 135 | +HOME_URL="https://www.ubuntu.com/" |
| 136 | +SUPPORT_URL="https://help.ubuntu.com/" |
| 137 | +BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" |
| 138 | +PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" |
| 139 | +UBUNTU_CODENAME=resolute |
| 140 | +LOGO=ubuntu-logo |
| 141 | +``` |
| 142 | + |
| 143 | +This confirms that the shell sandbox is running Arm Linux (Ubuntu on aarch64) inside the microVM. |
| 144 | + |
| 145 | +Keep the shell running to test management commands in another terminal. |
| 146 | + |
| 147 | +### Verify sandbox management commands |
| 148 | + |
| 149 | +In another terminal window, list all sandboxes with their agent and current status: |
| 150 | + |
| 151 | +```bash |
| 152 | +sbx ls |
| 153 | +``` |
| 154 | + |
| 155 | +The output is similar to: |
| 156 | + |
| 157 | +```output |
| 158 | +SANDBOX AGENT STATUS PORTS WORKSPACE |
| 159 | +shell-arm-learning-paths shell stopped /Users/arm-learning-paths |
| 160 | +``` |
| 161 | + |
| 162 | +Copy a file from your Mac into the sandbox. For example: |
| 163 | + |
| 164 | +```bash |
| 165 | +sbx cp ./myfile.txt <SANDBOX>:/home/user/myfile.txt |
| 166 | +``` |
| 167 | + |
| 168 | +Copy a file from a sandbox back to your Mac. For example: |
| 169 | + |
| 170 | +```bash |
| 171 | +sbx cp <SANDBOX>:/home/user/output.txt ./output.txt |
| 172 | +``` |
| 173 | + |
| 174 | +## Clean up |
| 175 | + |
| 176 | +Stop the running shell sandbox using its name: |
| 177 | + |
| 178 | +```bash |
| 179 | +sbx stop <SANDBOX> |
| 180 | +``` |
| 181 | + |
| 182 | +The running shell sandbox in the first terminal window stops. |
| 183 | + |
| 184 | +Remove the sandbox permanently: |
| 185 | + |
| 186 | +```bash |
| 187 | +sbx rm <SANDBOX> |
| 188 | +``` |
| 189 | + |
| 190 | +You'll be prompted to confirm whether you want to remove the sandbox. Answer `y` and press Enter to delete the sandbox. |
| 191 | + |
| 192 | +## Next steps |
| 193 | + |
| 194 | +You're now ready to use Docker Sandboxes to run AI agents in isolated microVMs on macOS. |
| 195 | + |
| 196 | +To launch an agent sandbox, provide the name of the agent sandbox in the run command. For example, to launch a Claude sandbox: |
| 197 | + |
| 198 | +```bash |
| 199 | +sbx run claude |
| 200 | +``` |
| 201 | + |
| 202 | +Other supported agent sandboxes include `copilot`, `codex`, and `kiro`. For the full list, see the [Docker Sandboxes agents documentation](https://docs.docker.com/ai/sandboxes/agents/). |
| 203 | + |
| 204 | +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-paths/servers-and-cloud-computing/arm-mcp-server/) Learning Path. |
0 commit comments