Skip to content

Commit 3166a19

Browse files
dvdksndvdksn
authored
Merge pull request #25807 from dvdksn/codex/document-sbx-linux-install
docs: separate sandbox installation from first run
2 parents 6d62ad9 + eab8d24 commit 3166a19

4 files changed

Lines changed: 130 additions & 138 deletions

File tree

‎content/guides/claude-code-sandbox-model-runner.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Before you start, make sure you have:
5252

5353
- [Docker Desktop](../get-started/get-docker.md) or Docker Engine installed
5454
- [Docker Model Runner enabled](../manuals/ai/model-runner/get-started.md#enable-docker-model-runner)
55-
- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/get-started.md#install-and-sign-in)
55+
- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/install.md)
5656

5757
If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or
5858
run:

‎content/manuals/ai/sandboxes/_index.md‎

Lines changed: 4 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -24,41 +24,8 @@ Available on a separate paid subscription.
2424

2525
## Get started
2626

27-
For complete system requirements, see the
28-
[get started prerequisites](get-started.md#prerequisites).
29-
30-
Install the `sbx` CLI and sign in:
31-
32-
{{< tabs >}}
33-
{{< tab name="macOS" >}}
34-
35-
```console
36-
$ brew trust docker/tap
37-
$ brew install docker/tap/sbx
38-
$ sbx login
39-
```
40-
41-
{{< /tab >}}
42-
{{< tab name="Windows" >}}
43-
44-
```powershell
45-
> winget install -h Docker.sbx
46-
> sbx login
47-
```
48-
49-
{{< /tab >}}
50-
{{< tab name="Linux (Ubuntu)" >}}
51-
52-
```console
53-
$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
54-
$ sudo apt-get install docker-sbx
55-
$ sudo usermod -aG kvm $USER
56-
$ newgrp kvm
57-
$ sbx login
58-
```
59-
60-
{{< /tab >}}
61-
{{< /tabs >}}
27+
Follow the [installation guide](install.md) to check the system requirements,
28+
install the `sbx` CLI, and sign in.
6229

6330
Then launch an agent in a sandbox:
6431

@@ -67,8 +34,8 @@ $ cd ~/my-project
6734
$ sbx run claude
6835
```
6936

70-
See the [get started guide](get-started.md) for a full walkthrough, or jump to
71-
the [usage guide](usage.md) for basic commands.
37+
See the [get started guide](get-started.md) for a first-session walkthrough, or
38+
jump to the [usage guide](usage.md) for basic commands.
7239

7340
## Learn more
7441

‎content/manuals/ai/sandboxes/get-started.md‎

Lines changed: 9 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -2,116 +2,25 @@
22
title: Get started with Docker Sandboxes
33
linkTitle: Get started
44
weight: 10
5-
description: Install the sbx CLI, configure credentials, and work through your first sandbox session.
6-
keywords: sandbox, sbx, get started, install, credentials, clone mode, network policy
5+
description: Configure agent credentials and work through your first Docker Sandboxes session.
6+
keywords: sandbox, sbx, get started, credentials, clone mode, network policy
77
---
88

99
Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
1010
sandbox gets its own Docker daemon, filesystem, and network — the agent can
1111
build containers, install packages, and modify files without touching your host
1212
system.
1313

14-
This page walks through your first session: install the CLI, run an agent in a
15-
sandbox, see how the sandbox isolates it, control what it can reach on the
16-
network, and clean up.
14+
This page walks through your first session: run an agent in a sandbox, see how
15+
the sandbox isolates it, control what it can reach on the network, and clean
16+
up.
1717

1818
## Prerequisites
1919

20-
{{< tabs group="os" >}}
21-
{{< tab name="macOS" >}}
22-
23-
- macOS Sonoma (version 14) or later
24-
- Apple silicon
25-
- An API key or authentication method for the agent you want to use. Most agents
26-
require an API key for their model provider (Anthropic, OpenAI, Google, and
27-
others). See the [agent pages](agents/) for provider-specific instructions.
28-
29-
{{< /tab >}}
30-
{{< tab name="Windows" >}}
31-
32-
- 64-bit Intel or AMD (x86_64)
33-
- Windows 11
34-
- Windows Hypervisor Platform enabled. Open an elevated PowerShell prompt (Run
35-
as Administrator) and run:
36-
```powershell
37-
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
38-
```
39-
- An API key or authentication method for the agent you want to use. Most agents
40-
require an API key for their model provider (Anthropic, OpenAI, Google, and
41-
others). See the [agent pages](agents/) for provider-specific instructions.
42-
43-
{{< /tab >}}
44-
{{< tab name="Linux (Ubuntu)" >}}
45-
46-
- Ubuntu 24.04 or later
47-
- 64-bit Intel or AMD (x86_64) or 64-bit Arm (aarch64)
48-
- KVM hardware virtualization supported and enabled by the CPU. If you're
49-
running inside a VM, nested virtualization must be turned on. Verify that KVM
50-
is available:
51-
```console
52-
$ lsmod | grep kvm
53-
```
54-
A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the output. If the output
55-
is empty, run `kvm-ok` for diagnostics. If KVM is unavailable, `sbx` will
56-
not start.
57-
- Your user in the `kvm` group:
58-
```console
59-
$ sudo usermod -aG kvm $USER
60-
```
61-
Log out and back in (or run `newgrp kvm`) for the group change to take effect.
62-
- An API key or authentication method for the agent you want to use. Most agents
63-
require an API key for their model provider (Anthropic, OpenAI, Google, and
64-
others). See the [agent pages](agents/) for provider-specific instructions.
65-
66-
{{< /tab >}}
67-
{{< /tabs >}}
68-
69-
If you run `sbx` in a virtual desktop infrastructure (VDI) environment, the
70-
environment must support nested virtualization.
71-
72-
Docker Desktop is not required to use `sbx`.
73-
74-
## Install and sign in
75-
76-
{{< tabs group="os" >}}
77-
{{< tab name="macOS" >}}
78-
79-
```console
80-
$ brew trust docker/tap
81-
$ brew install docker/tap/sbx
82-
$ sbx login
83-
```
84-
85-
{{< /tab >}}
86-
{{< tab name="Windows" >}}
87-
88-
```powershell
89-
> winget install -h Docker.sbx
90-
> sbx login
91-
```
92-
93-
{{< /tab >}}
94-
{{< tab name="Linux (Ubuntu)" >}}
95-
96-
```console
97-
$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
98-
$ sudo apt-get install docker-sbx
99-
$ sbx login
100-
```
101-
102-
The first command adds Docker's `apt` repository to your system.
103-
104-
{{< /tab >}}
105-
{{< /tabs >}}
106-
107-
If you need to install `sbx` manually, download a binary directly from the
108-
[sbx-releases](https://github.com/docker/sbx-releases/releases) repository.
109-
110-
`sbx login` opens a browser for Docker OAuth.
111-
112-
> [!NOTE]
113-
> See the [FAQ](faq.md) for details on why sign-in is required and what
114-
> happens with your data.
20+
- [Install the `sbx` CLI](install.md) and sign in to Docker
21+
- Configure an authentication method for the agent you want to use. Most agents
22+
require an API key for their model provider. See the [agent pages](agents/)
23+
for provider-specific instructions.
11524

11625
## Authenticate your agent
11726

‎content/manuals/ai/sandboxes/install.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Install Docker Sandboxes
3+
linkTitle: Install
4+
weight: 5
5+
description: Install the sbx CLI on macOS, Windows, or Linux and sign in to Docker Sandboxes.
6+
keywords: sandbox, sbx, install, macOS, Windows, Linux, Ubuntu
7+
---
8+
9+
Install the `sbx` CLI to run AI coding agents in isolated microVMs. You don't
10+
need Docker Desktop or Docker Engine to use `sbx`.
11+
12+
## Prerequisites
13+
14+
### macOS
15+
16+
- macOS Sonoma version 14 or later
17+
- Apple silicon
18+
19+
### Windows
20+
21+
- Windows 11
22+
- A 64-bit Intel or AMD processor
23+
- Windows Hypervisor Platform
24+
25+
To turn on Windows Hypervisor Platform, open an elevated PowerShell prompt and
26+
run:
27+
28+
```powershell
29+
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
30+
```
31+
32+
### Linux
33+
34+
- Ubuntu 24.04 or later
35+
- A 64-bit Intel or AMD processor, or a 64-bit Arm processor
36+
- KVM hardware virtualization supported and turned on by the CPU
37+
- Your user account in the `kvm` group
38+
39+
If you're running inside a virtual machine or virtual desktop infrastructure
40+
environment, the environment must support nested virtualization.
41+
42+
Verify that KVM is available:
43+
44+
```console
45+
$ lsmod | grep kvm
46+
```
47+
48+
A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the
49+
output. If the output is empty, run `kvm-ok` for diagnostics. `sbx` requires
50+
KVM to start.
51+
52+
Add your user to the `kvm` group:
53+
54+
```console
55+
$ sudo usermod -aG kvm $USER
56+
```
57+
58+
Sign out and back in, or run `newgrp kvm`, for the group change to take effect.
59+
60+
## Install on macOS
61+
62+
Install `sbx` using Homebrew:
63+
64+
```console
65+
$ brew trust docker/tap
66+
$ brew install docker/tap/sbx
67+
```
68+
69+
## Install on Windows
70+
71+
Install `sbx` using Windows Package Manager:
72+
73+
```powershell
74+
winget install -h Docker.sbx
75+
```
76+
77+
## Install on Linux
78+
79+
You can install `sbx` with Docker Engine or install only the `sbx` package.
80+
81+
### Install Docker Engine and SBX
82+
83+
Run Docker's convenience script with `SBX=1` to install Docker Engine and the
84+
`docker-sbx` package together:
85+
86+
```console
87+
$ curl -fsSL https://get.docker.com | sudo SBX=1 sh
88+
```
89+
90+
### Install SBX only
91+
92+
To install `sbx` without Docker Engine on the host, add Docker's `apt`
93+
repository and install the `docker-sbx` package:
94+
95+
```console
96+
$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
97+
$ sudo apt-get install docker-sbx
98+
```
99+
100+
## Install manually
101+
102+
To install `sbx` without a package manager, download a binary from the
103+
[sbx-releases repository](https://github.com/docker/sbx-releases/releases).
104+
105+
## Sign in
106+
107+
Sign in to Docker:
108+
109+
```console
110+
$ sbx login
111+
```
112+
113+
The command opens a browser for Docker OAuth. See the [FAQ](faq.md) for why
114+
sign-in is required and how Docker handles your data.
115+
116+
After signing in, [run your first sandbox](get-started.md).

0 commit comments

Comments
 (0)