Getting Started

Prerequisites
Install the sbx CLI
Verify the installation and sign in
Understanding the sbx CLI
Create your first sandbox
Exit and re-enter
Stop and remove
Beginner Pitfalls

1. Prerequisites

macOS: Sonoma (14) or later, Apple silicon.
Windows: Windows 11, 64-bit Intel/AMD, with Windows Hypervisor Platform turned on.
Linux: Ubuntu 24.04 or later, 64-bit Intel/AMD or Arm, with KVM hardware virtualization available and your user in the kvm group.

You don't need Docker Desktop or a separate Docker Engine install to use sbx — it ships its own sandbox daemon.

Note: On Linux, confirm KVM is available before installing:
lsmod | grep kvm
You should see kvm_intel, kvm_amd, or kvm in the output. If nothing prints, sbx won't be able to start sandboxes.

2. Install the sbx CLI

macOS (Homebrew):

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

Windows (WinGet, current user, no admin required):

winget install -h Docker.sbx

Linux (Ubuntu) — install sbx only, without a full Docker Engine:

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt install docker-sbx

Note: these are the exact install paths documented at docs.docker.com/ai/sandboxes/install at the time of writing. Docker Sandboxes ships fast — if a command below errors out, check that page for what changed.

sbx version

Then sign in — sandboxes are tied to your Docker account:

sbx login

This opens a browser for Docker OAuth. Once it completes, you're ready to create a sandbox.

4. Understanding the sbx CLI

sbx is one binary with subcommands, the same shape as the docker CLI:

sbx run       # create (or re-attach to) a sandbox and start something in it
sbx ls        # list your sandboxes
sbx exec      # run a command inside a running sandbox
sbx ports     # publish/unpublish ports on a sandbox
sbx stop      # pause a sandbox without deleting it
sbx rm        # delete a sandbox and everything in it
sbx prune     # delete all stopped sandboxes at once
sbx diagnose  # check your sbx installation for common problems

You'll use every one of these before this course is over. Run sbx with no arguments at any point to open an interactive dashboard — a live list of your sandboxes you can attach to, open a shell in, or remove, without memorizing flags.

5. Create your first sandbox

From a project directory (or any empty folder — we won't need real project files until Part 4), create a named sandbox running a plain shell instead of an AI agent:

mkdir -p ~/sbx-crash-course && cd ~/sbx-crash-course
sbx run --name sbx-crash-course shell

The first time you run any sandbox, sbx asks you to pick a network policy:

1. Open         — All network traffic allowed, no restrictions.
2. Balanced     — Default deny, with common dev sites allowed.
3. Locked Down  — All network traffic blocked unless you allow it.

Pick Balanced. It's the default recommendation, and it's enough to apt-get install, npm install, and docker pull throughout this course without extra configuration.

The first run takes a little longer while the base image downloads. You land in a Bash prompt inside the sandbox — this is a different machine from your host, running its own Linux, with the ~/sbx-crash-course directory you started from mounted in as your workspace.

Confirm it's running, from another terminal on your host:

sbx ls

SANDBOX               AGENT   STATUS    PORTS   WORKSPACE
sbx-crash-course       shell   running           ~/sbx-crash-course

6. Exit and re-enter

Detach without stopping the sandbox with Ctrl-\ (the default detach gesture), or just exit the shell normally with exit / Ctrl-D — either way, the sandbox itself keeps existing (though exit also ends the shell session, so you'll reattach the same way).

Re-enter it any time with the same --name:

sbx run --name sbx-crash-course

Notice the agent name is optional on re-attach — sbx reads it from the sandbox's own spec. You'll land back in the same shell, in the same directory, with anything you installed still there.

7. Stop and remove

Stop pauses the sandbox without deleting it — installed packages, pulled images, and files all persist, ready to resume later:

sbx stop sbx-crash-course

Remove deletes the sandbox and everything inside it. Don't run this yet — we're about to build on this same sandbox for the rest of the course — but this is the command you'll reach for once you're done experimenting:

sbx rm sbx-crash-course

If you ever want a clean slate for a fresh start, stop then rm then run again gets you a brand-new sandbox under the same name.

8. Beginner Pitfalls

sbx run <agent> reconnects to an existing sandbox for the same workspace path or --name instead of creating a new one — you won't accidentally pile up duplicate sandboxes just by running the command again.
sbx stop does not delete anything. Only sbx rm (or sbx prune for all stopped sandboxes at once) actually deletes sandbox data.
If sbx run seems to hang or error strangely, don't immediately reach for sbx rm — try sbx diagnose first. We cover this properly in Part 7.