Docker Sandboxes (sbx)

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.

On macOS with Apple Silicon, sbx uses Apple’s virtualization framework to launch Arm Linux (Ubuntu) microVMs. You don’t need Docker Desktop.

Before you begin

You need:

• A Mac with Apple Silicon (M1 or later) running macOS Sonoma (version 14) or later.
• A Docker Hub account to authenticate sbx.
• Homebrew installed.

Install the sbx CLI

Install sbx using Homebrew:

    

        
        
brew install docker/tap/sbx

    

Homebrew installs the sbx binary at /opt/homebrew/bin/sbx.

Verify the installation

After installing the CLI, verify that the installation was successful.

Check the sbx CLI version

Start by checking what version of sbx is installed:

    

        
        
sbx version

    

The output is similar to:

    

        
        sbx version: v0.32.0 55580366449bcfebfc1787b9944284cf64c856d7

        
    

Authenticate with Docker Hub

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.

Start a shell sandbox

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.

Confirm the sandbox runs Arm Linux

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.

Verify sandbox management commands

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           /Users/arm-learning-paths

        
    

Copy a file from your Mac into the sandbox. For example:

    

        
        
sbx cp ./myfile.txt <SANDBOX>:/home/user/myfile.txt

    

Copy a file from a sandbox back to your Mac. For example:

    

        
        
sbx cp <SANDBOX>:/home/user/output.txt ./output.txt

    

Clean up

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.

Next steps

You’re now ready to use Docker Sandboxes to run AI agents in isolated microVMs on macOS.

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.