From eab8d2471037dd3c5b9b09938ef71027d67476ca Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 12 Aug 2026 08:37:51 +0000 Subject: [PATCH] docs: separate sandbox installation from first run The sandbox get-started page mixed platform installation with the first-session walkthrough. Add a dedicated install page with both Linux installation paths, and update related links to use it. --- .../claude-code-sandbox-model-runner.md | 2 +- content/manuals/ai/sandboxes/_index.md | 41 +------ content/manuals/ai/sandboxes/get-started.md | 109 ++-------------- content/manuals/ai/sandboxes/install.md | 116 ++++++++++++++++++ 4 files changed, 130 insertions(+), 138 deletions(-) create mode 100644 content/manuals/ai/sandboxes/install.md diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md index 8b6e58d7e643..297f8a72988b 100644 --- a/content/guides/claude-code-sandbox-model-runner.md +++ b/content/guides/claude-code-sandbox-model-runner.md @@ -52,7 +52,7 @@ Before you start, make sure you have: - [Docker Desktop](../get-started/get-docker.md) or Docker Engine installed - [Docker Model Runner enabled](../manuals/ai/model-runner/get-started.md#enable-docker-model-runner) -- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/get-started.md#install-and-sign-in) +- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/install.md) If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run: diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 455fffa2e1b4..764ce9b097fe 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -24,41 +24,8 @@ Available on a separate paid subscription. ## Get started -For complete system requirements, see the -[get started prerequisites](get-started.md#prerequisites). - -Install the `sbx` CLI and sign in: - -{{< tabs >}} -{{< tab name="macOS" >}} - -```console -$ brew trust docker/tap -$ brew install docker/tap/sbx -$ sbx login -``` - -{{< /tab >}} -{{< tab name="Windows" >}} - -```powershell -> winget install -h Docker.sbx -> sbx login -``` - -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} - -```console -$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh -$ sudo apt-get install docker-sbx -$ sudo usermod -aG kvm $USER -$ newgrp kvm -$ sbx login -``` - -{{< /tab >}} -{{< /tabs >}} +Follow the [installation guide](install.md) to check the system requirements, +install the `sbx` CLI, and sign in. Then launch an agent in a sandbox: @@ -67,8 +34,8 @@ $ cd ~/my-project $ sbx run claude ``` -See the [get started guide](get-started.md) for a full walkthrough, or jump to -the [usage guide](usage.md) for basic commands. +See the [get started guide](get-started.md) for a first-session walkthrough, or +jump to the [usage guide](usage.md) for basic commands. ## Learn more diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 7a709b1f8c09..5af20a4eb782 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -2,8 +2,8 @@ title: Get started with Docker Sandboxes linkTitle: Get started weight: 10 -description: Install the sbx CLI, configure credentials, and work through your first sandbox session. -keywords: sandbox, sbx, get started, install, credentials, clone mode, network policy +description: Configure agent credentials and work through your first Docker Sandboxes session. +keywords: sandbox, sbx, get started, credentials, clone mode, network policy --- Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each @@ -11,107 +11,16 @@ sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system. -This page walks through your first session: install the CLI, run an agent in a -sandbox, see how the sandbox isolates it, control what it can reach on the -network, and clean up. +This page walks through your first session: run an agent in a sandbox, see how +the sandbox isolates it, control what it can reach on the network, and clean +up. ## Prerequisites -{{< tabs group="os" >}} -{{< tab name="macOS" >}} - -- macOS Sonoma (version 14) or later -- Apple silicon -- An API key or authentication method for the agent you want to use. Most agents - require an API key for their model provider (Anthropic, OpenAI, Google, and - others). See the [agent pages](agents/) for provider-specific instructions. - -{{< /tab >}} -{{< tab name="Windows" >}} - -- 64-bit Intel or AMD (x86_64) -- Windows 11 -- Windows Hypervisor Platform enabled. Open an elevated PowerShell prompt (Run - as Administrator) and run: - ```powershell - Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All - ``` -- An API key or authentication method for the agent you want to use. Most agents - require an API key for their model provider (Anthropic, OpenAI, Google, and - others). See the [agent pages](agents/) for provider-specific instructions. - -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} - -- Ubuntu 24.04 or later -- 64-bit Intel or AMD (x86_64) or 64-bit Arm (aarch64) -- KVM hardware virtualization supported and enabled by the CPU. If you're - running inside a VM, nested virtualization must be turned on. Verify that KVM - is available: - ```console - $ lsmod | grep kvm - ``` - A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the output. If the output - is empty, run `kvm-ok` for diagnostics. If KVM is unavailable, `sbx` will - not start. -- Your user in the `kvm` group: - ```console - $ sudo usermod -aG kvm $USER - ``` - Log out and back in (or run `newgrp kvm`) for the group change to take effect. -- An API key or authentication method for the agent you want to use. Most agents - require an API key for their model provider (Anthropic, OpenAI, Google, and - others). See the [agent pages](agents/) for provider-specific instructions. - -{{< /tab >}} -{{< /tabs >}} - -If you run `sbx` in a virtual desktop infrastructure (VDI) environment, the -environment must support nested virtualization. - -Docker Desktop is not required to use `sbx`. - -## Install and sign in - -{{< tabs group="os" >}} -{{< tab name="macOS" >}} - -```console -$ brew trust docker/tap -$ brew install docker/tap/sbx -$ sbx login -``` - -{{< /tab >}} -{{< tab name="Windows" >}} - -```powershell -> winget install -h Docker.sbx -> sbx login -``` - -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} - -```console -$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh -$ sudo apt-get install docker-sbx -$ sbx login -``` - -The first command adds Docker's `apt` repository to your system. - -{{< /tab >}} -{{< /tabs >}} - -If you need to install `sbx` manually, download a binary directly from the -[sbx-releases](https://github.com/docker/sbx-releases/releases) repository. - -`sbx login` opens a browser for Docker OAuth. - -> [!NOTE] -> See the [FAQ](faq.md) for details on why sign-in is required and what -> happens with your data. +- [Install the `sbx` CLI](install.md) and sign in to Docker +- Configure an authentication method for the agent you want to use. Most agents + require an API key for their model provider. See the [agent pages](agents/) + for provider-specific instructions. ## Authenticate your agent diff --git a/content/manuals/ai/sandboxes/install.md b/content/manuals/ai/sandboxes/install.md new file mode 100644 index 000000000000..cffa34002f1c --- /dev/null +++ b/content/manuals/ai/sandboxes/install.md @@ -0,0 +1,116 @@ +--- +title: Install Docker Sandboxes +linkTitle: Install +weight: 5 +description: Install the sbx CLI on macOS, Windows, or Linux and sign in to Docker Sandboxes. +keywords: sandbox, sbx, install, macOS, Windows, Linux, Ubuntu +--- + +Install the `sbx` CLI to run AI coding agents in isolated microVMs. You don't +need Docker Desktop or Docker Engine to use `sbx`. + +## Prerequisites + +### macOS + +- macOS Sonoma version 14 or later +- Apple silicon + +### Windows + +- Windows 11 +- A 64-bit Intel or AMD processor +- Windows Hypervisor Platform + +To turn on Windows Hypervisor Platform, open an elevated PowerShell prompt and +run: + +```powershell +Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All +``` + +### Linux + +- Ubuntu 24.04 or later +- A 64-bit Intel or AMD processor, or a 64-bit Arm processor +- KVM hardware virtualization supported and turned on by the CPU +- Your user account in the `kvm` group + +If you're running inside a virtual machine or virtual desktop infrastructure +environment, the environment must support nested virtualization. + +Verify that KVM is available: + +```console +$ lsmod | grep kvm +``` + +A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the +output. If the output is empty, run `kvm-ok` for diagnostics. `sbx` requires +KVM to start. + +Add your user to the `kvm` group: + +```console +$ sudo usermod -aG kvm $USER +``` + +Sign out and back in, or run `newgrp kvm`, for the group change to take effect. + +## Install on macOS + +Install `sbx` using Homebrew: + +```console +$ brew trust docker/tap +$ brew install docker/tap/sbx +``` + +## Install on Windows + +Install `sbx` using Windows Package Manager: + +```powershell +winget install -h Docker.sbx +``` + +## Install on Linux + +You can install `sbx` with Docker Engine or install only the `sbx` package. + +### Install Docker Engine and SBX + +Run Docker's convenience script with `SBX=1` to install Docker Engine and the +`docker-sbx` package together: + +```console +$ curl -fsSL https://get.docker.com | sudo SBX=1 sh +``` + +### Install SBX only + +To install `sbx` without Docker Engine on the host, add Docker's `apt` +repository and install the `docker-sbx` package: + +```console +$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh +$ sudo apt-get install docker-sbx +``` + +## Install manually + +To install `sbx` without a package manager, download a binary from the +[sbx-releases repository](https://github.com/docker/sbx-releases/releases). + +## Sign in + +Sign in to Docker: + +```console +$ sbx login +``` + +The command opens a browser for Docker OAuth. See the [FAQ](faq.md) for why +sign-in is required and how Docker handles your data. + +After signing in, [run your first sandbox](get-started.md).