Skip to content

Commit cdde205

Browse files
dvdksndvdksn
committed
sandboxes: add sbx documentation
Add full documentation for the sbx CLI sandbox experience including get-started, usage guide, architecture, agents (claude-code, codex, copilot, gemini, kiro, opencode, cagent, custom-environments), security (isolation, credentials, policy, workspace trust), troubleshooting, and FAQ. Update _index.md as the section landing page. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
1 parent 258466b commit cdde205

69 files changed

Lines changed: 3981 additions & 19 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ Turtlesim
237237
typesafe
238238
Ubuntu
239239
ufw
240+
uv
240241
umask
241242
uncaptured
242243
Uncaptured
@@ -259,6 +260,9 @@ windowsfilter
259260
WireMock
260261
workdir
261262
WORKDIR
263+
[Ww]orktrees?
264+
[Pp]assthrough
265+
[Pp]reconfigured
262266
Xdebug
263267
xUnit
264268
XQuartz

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

Lines changed: 60 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,66 @@ weight: 20
55
params:
66
sidebar:
77
group: AI
8+
badge:
9+
color: violet
10+
text: Experimental
811
---
912

10-
Docker Sandboxes let you run AI coding agents in isolated environments using
11-
the `docker sandbox` command. Sandboxes require Docker Desktop and run agents
12-
in microVMs with private Docker daemons.
13+
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
1314

14-
For setup instructions and usage details, see the
15-
[Docker Desktop sandboxes](docker-desktop.md) page.
15+
Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
16+
sandbox gets its own Docker daemon, filesystem, and network — the agent can
17+
build containers, install packages, and modify files without touching your host
18+
system.
19+
20+
## Get started
21+
22+
Install the `sbx` CLI and sign in:
23+
24+
{{< tabs >}}
25+
{{< tab name="macOS" >}}
26+
27+
```console
28+
$ brew install docker/tap/sbx
29+
$ sbx login
30+
```
31+
32+
{{< /tab >}}
33+
{{< tab name="Windows" >}}
34+
35+
```powershell
36+
> winget install -h Docker.sbx
37+
> sbx login
38+
```
39+
40+
{{< /tab >}}
41+
{{< /tabs >}}
42+
43+
Then launch an agent in a sandbox:
44+
45+
```console
46+
$ cd ~/my-project
47+
$ sbx run claude
48+
```
49+
50+
See the [get started guide](get-started.md) for a full walkthrough, or jump to
51+
the [usage guide](usage.md) for common patterns.
52+
53+
## Learn more
54+
55+
- [Agents](agents/) — supported agents and per-agent configuration
56+
- [Custom environments](agents/custom-environments.md) — build reusable sandbox
57+
images with pre-installed tools
58+
- [Architecture](architecture.md) — microVM isolation, workspace mounting,
59+
networking
60+
- [Security](security/) — isolation model, credential handling, network
61+
policies, workspace trust
62+
- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
63+
- [Troubleshooting](troubleshooting.md) — common issues and fixes
64+
- [FAQ](faq.md) — login requirements, telemetry, etc
65+
66+
## Docker Desktop integration
67+
68+
Docker Desktop also includes a [built-in sandbox command](docker-desktop.md)
69+
(`docker sandbox`) with a subset of features. The `sbx` CLI is recommended for
70+
most use cases.

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Supported agents
3+
linkTitle: Agents
4+
weight: 30
5+
description: AI coding agents supported by Docker Sandboxes.
6+
---
7+
8+
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
9+
10+
Docker Sandboxes runs the following agents out of the box:
11+
12+
- [Claude Code](claude-code/)
13+
- [Codex](codex/)
14+
- [Copilot](copilot/)
15+
- [Gemini](gemini/)
16+
- [Kiro](kiro/)
17+
- [OpenCode](opencode/)
18+
- [Docker Agent](docker-agent/)
19+
20+
Want to pre-install tools or customize an agent's environment?
21+
See [Custom environments](custom-environments/).

‎content/manuals/ai/sandboxes/agents/claude-code.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Claude Code
3+
weight: 10
4+
description: |
5+
Use Claude Code in Docker Sandboxes with authentication, configuration, and
6+
YOLO mode for AI-assisted development.
7+
---
8+
9+
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
10+
11+
Official documentation: [Claude Code](https://code.claude.com/docs)
12+
13+
## Quick start
14+
15+
Launch Claude Code in a sandbox by pointing it at a project directory:
16+
17+
```console
18+
$ sbx run claude ~/my-project
19+
```
20+
21+
The workspace parameter defaults to the current directory, so `sbx run claude`
22+
from inside your project works too. To start Claude with a specific prompt:
23+
24+
```console
25+
$ sbx run claude --name my-sandbox -- "Add error handling to the login function"
26+
```
27+
28+
Everything after `--` is passed directly to Claude Code. You can also pipe in a
29+
prompt from a file with `-- "$(cat prompt.txt)"`.
30+
31+
## Authentication
32+
33+
Claude Code requires either an Anthropic API key or a Claude subscription.
34+
35+
**API key**: Store your key using
36+
[stored secrets](../security/credentials.md#stored-secrets):
37+
38+
```console
39+
$ sbx secret set -g anthropic
40+
```
41+
42+
Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your
43+
shell before running the sandbox. See
44+
[Credentials](../security/credentials.md) for details on both methods.
45+
46+
**Claude subscription**: If no API key is set, Claude Code prompts you to
47+
authenticate interactively using OAuth. The proxy handles the OAuth flow, so
48+
credentials aren't stored inside the sandbox.
49+
50+
## Configuration
51+
52+
Sandboxes don't pick up user-level configuration from your host, such as
53+
`~/.claude`. Only project-level configuration in the working directory is
54+
available inside the sandbox. See
55+
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
56+
for workarounds.
57+
58+
Any Claude Code CLI options can be passed after the `--` separator:
59+
60+
```console
61+
$ sbx run claude --name my-sandbox -- --continue
62+
```
63+
64+
See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
65+
for available options.
66+
67+
## Base image
68+
69+
The sandbox uses `docker/sandbox-templates:claude-code` and launches Claude Code
70+
with `--dangerously-skip-permissions` by default. See
71+
[Custom environments](custom-environments.md) to build your own image on
72+
top of this base.

‎content/manuals/ai/sandboxes/agents/codex.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Codex
3+
weight: 20
4+
description: |
5+
Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO
6+
mode configuration.
7+
---
8+
9+
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
10+
11+
This guide covers authentication, configuration, and usage of Codex in a
12+
sandboxed environment.
13+
14+
Official documentation: [Codex CLI](https://developers.openai.com/codex/cli)
15+
16+
## Quick start
17+
18+
Create a sandbox and run Codex for a project directory:
19+
20+
```console
21+
$ sbx run codex ~/my-project
22+
```
23+
24+
The workspace parameter is optional and defaults to the current directory:
25+
26+
```console
27+
$ cd ~/my-project
28+
$ sbx run codex
29+
```
30+
31+
## Authentication
32+
33+
Codex requires an OpenAI API key. Store your key using
34+
[stored secrets](../security/credentials.md#stored-secrets):
35+
36+
```console
37+
$ sbx secret set -g openai
38+
```
39+
40+
Alternatively, export the `OPENAI_API_KEY` environment variable in your shell
41+
before running the sandbox. See
42+
[Credentials](../security/credentials.md) for details on both methods.
43+
44+
## Configuration
45+
46+
Sandboxes don't pick up user-level configuration from your host, such as
47+
`~/.codex`. Only project-level configuration in the working directory is
48+
available inside the sandbox. See
49+
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
50+
for workarounds.
51+
52+
The sandbox runs Codex without approval prompts by default. Pass additional
53+
Codex CLI options after `--`:
54+
55+
```console
56+
$ sbx run codex --name <sandbox-name> -- <codex-options>
57+
```
58+
59+
## Base image
60+
61+
Template: `docker/sandbox-templates:codex`
62+
63+
Preconfigured to run without approval prompts.
64+
65+
See [Custom environments](custom-environments.md) to pre-install tools or
66+
customize this environment.

‎content/manuals/ai/sandboxes/agents/copilot.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Copilot
3+
weight: 30
4+
description: |
5+
Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and
6+
trusted folder configuration.
7+
---
8+
9+
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
10+
11+
This guide covers authentication, configuration, and usage of GitHub Copilot
12+
in a sandboxed environment.
13+
14+
Official documentation: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)
15+
16+
## Quick start
17+
18+
Create a sandbox and run Copilot for a project directory:
19+
20+
```console
21+
$ sbx run copilot ~/my-project
22+
```
23+
24+
The workspace parameter is optional and defaults to the current directory:
25+
26+
```console
27+
$ cd ~/my-project
28+
$ sbx run copilot
29+
```
30+
31+
## Authentication
32+
33+
Copilot requires a GitHub token with Copilot access. Store your token using
34+
[stored secrets](../security/credentials.md#stored-secrets):
35+
36+
```console
37+
$ echo "$(gh auth token)" | sbx secret set -g github
38+
```
39+
40+
Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in
41+
your shell before running the sandbox. See
42+
[Credentials](../security/credentials.md) for details on both methods.
43+
44+
## Configuration
45+
46+
Sandboxes don't pick up user-level configuration from your host. Only
47+
project-level configuration in the working directory is available inside the
48+
sandbox. See
49+
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
50+
for workarounds.
51+
52+
Copilot is configured to trust the workspace directory by default, so it
53+
operates without repeated confirmations for workspace files.
54+
55+
### Pass options at runtime
56+
57+
Pass Copilot CLI options after `--`:
58+
59+
```console
60+
$ sbx run copilot --name <sandbox-name> -- <copilot-options>
61+
```
62+
63+
## Base image
64+
65+
Template: `docker/sandbox-templates:copilot`
66+
67+
Preconfigured to trust the workspace directory and run without approval prompts.
68+
69+
See [Custom environments](custom-environments.md) to pre-install tools or
70+
customize this environment.

0 commit comments

Comments
 (0)