centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-04-12 06:19:22 +07:00
Code Issues Packages Projects Releases Wiki Activity

sandboxes: add sbx documentation

Browse Source 
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>
This commit is contained in:
David Karlsson
2026-03-09 09:41:02 +01:00
parent 258466b72a
commit cdde205ba8
69 changed files with 3981 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
_vale/config/vocabularies/Docker/accept.txt
View File

@@ -237,6 +237,7 @@ Turtlesim
typesafe
Ubuntu
ufw
uv
umask
uncaptured
Uncaptured
@@ -259,6 +260,9 @@ windowsfilter
WireMock
workdir
WORKDIR
[Ww]orktrees?
[Pp]assthrough
[Pp]reconfigured
Xdebug
xUnit
XQuartz

65
content/manuals/ai/sandboxes/_index.md
View File

@@ -5,11 +5,66 @@ weight: 20
params:
sidebar:
group: AI
badge:
color: violet
text: Experimental
---
Docker Sandboxes let you run AI coding agents in isolated environments using
the `docker sandbox` command. Sandboxes require Docker Desktop and run agents
in microVMs with private Docker daemons.
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
For setup instructions and usage details, see the
[Docker Desktop sandboxes](docker-desktop.md) page.
Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
sandbox gets its own Docker daemon, filesystem, and network — the agent can
build containers, install packages, and modify files without touching your host
system.
## Get started
Install the `sbx` CLI and sign in:
{{< tabs >}}
{{< tab name="macOS" >}}
```console
$ brew install docker/tap/sbx
$ sbx login
```
{{< /tab >}}
{{< tab name="Windows" >}}
```powershell
> winget install -h Docker.sbx
> sbx login
```
{{< /tab >}}
{{< /tabs >}}
Then launch an agent in a sandbox:
```console
$ 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 common patterns.
## Learn more
- [Agents](agents/) — supported agents and per-agent configuration
- [Custom environments](agents/custom-environments.md) — build reusable sandbox
images with pre-installed tools
- [Architecture](architecture.md) — microVM isolation, workspace mounting,
networking
- [Security](security/) — isolation model, credential handling, network
policies, workspace trust
- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
- [Troubleshooting](troubleshooting.md) — common issues and fixes
- [FAQ](faq.md) — login requirements, telemetry, etc
## Docker Desktop integration
Docker Desktop also includes a [built-in sandbox command](docker-desktop.md)
(`docker sandbox`) with a subset of features. The `sbx` CLI is recommended for
most use cases.

21
content/manuals/ai/sandboxes/agents/_index.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: Supported agents
linkTitle: Agents
weight: 30
description: AI coding agents supported by Docker Sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Docker Sandboxes runs the following agents out of the box:
- [Claude Code](claude-code/)
- [Codex](codex/)
- [Copilot](copilot/)
- [Gemini](gemini/)
- [Kiro](kiro/)
- [OpenCode](opencode/)
- [Docker Agent](docker-agent/)
Want to pre-install tools or customize an agent's environment?
See [Custom environments](custom-environments/).

72
content/manuals/ai/sandboxes/agents/claude-code.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Claude Code
weight: 10
description: |
Use Claude Code in Docker Sandboxes with authentication, configuration, and
YOLO mode for AI-assisted development.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Official documentation: [Claude Code](https://code.claude.com/docs)
## Quick start
Launch Claude Code in a sandbox by pointing it at a project directory:
```console
$ sbx run claude ~/my-project
```
The workspace parameter defaults to the current directory, so `sbx run claude`
from inside your project works too. To start Claude with a specific prompt:
```console
$ sbx run claude --name my-sandbox -- "Add error handling to the login function"
```
Everything after `--` is passed directly to Claude Code. You can also pipe in a
prompt from a file with `-- "$(cat prompt.txt)"`.
## Authentication
Claude Code requires either an Anthropic API key or a Claude subscription.
**API key**: Store your key using
[stored secrets](../security/credentials.md#stored-secrets):
```console
$ sbx secret set -g anthropic
```
Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your
shell before running the sandbox. See
[Credentials](../security/credentials.md) for details on both methods.
**Claude subscription**: If no API key is set, Claude Code prompts you to
authenticate interactively using OAuth. The proxy handles the OAuth flow, so
credentials aren't stored inside the sandbox.
## Configuration
Sandboxes don't pick up user-level configuration from your host, such as
`~/.claude`. Only project-level configuration in the working directory is
available inside the sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
Any Claude Code CLI options can be passed after the `--` separator:
```console
$ sbx run claude --name my-sandbox -- --continue
```
See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
for available options.
## Base image
The sandbox uses `docker/sandbox-templates:claude-code` and launches Claude Code
with `--dangerously-skip-permissions` by default. See
[Custom environments](custom-environments.md) to build your own image on
top of this base.

66
content/manuals/ai/sandboxes/agents/codex.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Codex
weight: 20
description: |
Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO
mode configuration.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This guide covers authentication, configuration, and usage of Codex in a
sandboxed environment.
Official documentation: [Codex CLI](https://developers.openai.com/codex/cli)
## Quick start
Create a sandbox and run Codex for a project directory:
```console
$ sbx run codex ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ sbx run codex
```
## Authentication
Codex requires an OpenAI API key. Store your key using
[stored secrets](../security/credentials.md#stored-secrets):
```console
$ sbx secret set -g openai
```
Alternatively, export the `OPENAI_API_KEY` environment variable in your shell
before running the sandbox. See
[Credentials](../security/credentials.md) for details on both methods.
## Configuration
Sandboxes don't pick up user-level configuration from your host, such as
`~/.codex`. Only project-level configuration in the working directory is
available inside the sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
The sandbox runs Codex without approval prompts by default. Pass additional
Codex CLI options after `--`:
```console
$ sbx run codex --name <sandbox-name> -- <codex-options>
```
## Base image
Template: `docker/sandbox-templates:codex`
Preconfigured to run without approval prompts.
See [Custom environments](custom-environments.md) to pre-install tools or
customize this environment.

70
content/manuals/ai/sandboxes/agents/copilot.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: Copilot
weight: 30
description: |
Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and
trusted folder configuration.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This guide covers authentication, configuration, and usage of GitHub Copilot
in a sandboxed environment.
Official documentation: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)
## Quick start
Create a sandbox and run Copilot for a project directory:
```console
$ sbx run copilot ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ sbx run copilot
```
## Authentication
Copilot requires a GitHub token with Copilot access. Store your token using
[stored secrets](../security/credentials.md#stored-secrets):
```console
$ echo "$(gh auth token)" | sbx secret set -g github
```
Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in
your shell before running the sandbox. See
[Credentials](../security/credentials.md) for details on both methods.
## Configuration
Sandboxes don't pick up user-level configuration from your host. Only
project-level configuration in the working directory is available inside the
sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
Copilot is configured to trust the workspace directory by default, so it
operates without repeated confirmations for workspace files.
### Pass options at runtime
Pass Copilot CLI options after `--`:
```console
$ sbx run copilot --name <sandbox-name> -- <copilot-options>
```
## Base image
Template: `docker/sandbox-templates:copilot`
Preconfigured to trust the workspace directory and run without approval prompts.
See [Custom environments](custom-environments.md) to pre-install tools or
customize this environment.

176
content/manuals/ai/sandboxes/agents/custom-environments.md Normal file
View File

@@ -0,0 +1,176 @@
---
title: Custom environments
weight: 80
description: Customize agent sandbox environments or use the shell sandbox for manual setup.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Every sandbox is customizable — agents install packages, pull images, and
configure tools as they work, and those changes persist for the sandbox's
lifetime. This page covers two things beyond that: a general-purpose shell
sandbox for manual setup, and custom templates that capture a configured
environment into a reusable image so you don't have to set it up again every
time.
## Shell sandbox
`sbx run shell` drops you into a Bash login shell inside a sandbox
with no pre-installed agent binary. It's useful for installing and
configuring agents manually, testing custom implementations, or inspecting a
running environment.
```console
$ sbx run shell ~/my-project
```
The workspace path defaults to the current directory. To run a one-off command
instead of an interactive shell, pass it after `--`:
```console
$ sbx run shell -- -c "echo 'Hello from sandbox'"
```
Set your API keys as environment variables so the sandbox proxy can inject them
into API requests automatically. Credentials are never stored inside the VM:
```console
$ export ANTHROPIC_API_KEY=sk-ant-xxxxx
$ export OPENAI_API_KEY=sk-xxxxx
```
Once inside the shell, you can install agents using their standard methods,
for example `npm install -g @continuedev/cli`. For complex setups, build a
[custom template](#custom-templates) instead of installing interactively each
time.
The shell sandbox uses the `shell` base image — the common base environment
without a pre-installed agent.
## Custom templates
Custom templates are reusable sandbox images that extend one of the built-in
agent environments with additional tools and configuration baked in. Instead of
asking the agent to install packages every time, build a template once and
reuse it across sandboxes and team members.
Templates make sense when multiple people need the same environment, when setup
involves steps that are tedious to repeat, or when you need pinned versions of
specific tools. For one-off work, the default image is fine — ask the agent to
install what's needed.
> [!NOTE]
> Custom templates customize an existing agent's environment — they don't
> create new agent runtimes. The agent that launches inside the sandbox is
> determined by the base image variant you extend and the agent you specify
> in the `sbx run` command, not by binaries installed in the template.
### Base images
All sandbox templates are published as
`docker/sandbox-templates:<variant>`. They are based on Ubuntu and run as a
non-root `agent` user with sudo access. Most variants include Git, Docker
CLI, and common development tools like Node.js, Python, Go, and Java.
| Variant | Agent |
| --------------------- | -------------------------------------------------------------------- |
| `claude-code` | [Claude Code](https://claude.ai/download) |
| `claude-code-minimal` | Claude Code with a minimal toolset (no Node.js, Python, Go, or Java) |
| `codex` | [OpenAI Codex](https://github.com/openai/codex) |
| `copilot` | [GitHub Copilot](https://github.com/github/copilot-cli) |
| `docker-agent` | [Docker Agent](https://github.com/docker/docker-agent) |
| `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) |
| `kiro` | [Kiro](https://kiro.dev) |
| `opencode` | [OpenCode](https://opencode.ai) |
| `shell` | No agent pre-installed. Use for manual agent setup. |
Each variant also has a `-docker` version (for example,
`claude-code-docker`) that includes a full Docker Engine running inside the
sandbox. The `-docker` variants are the defaults used by `sbx run` on macOS
and Linux. They run in privileged mode with a dedicated block volume at
`/var/lib/docker`, and `dockerd` starts automatically.
The block volume defaults to 50 GB and uses a sparse file, so it only
consumes disk space as Docker writes to it. On Windows, the volume is not
sparse and the full 50 GB is allocated at creation time, which increases
startup time. For this reason, the non-docker variants are the default on
Windows.
To override the volume size, set the `DOCKER_SANDBOXES_DOCKER_SIZE`
environment variable to a size string before starting the sandbox:
```console
$ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude
```
Use the non-docker variant if you don't need to build or run containers
inside the sandbox and want a lighter, non-privileged environment. Specify
it explicitly with `--template`:
```console
$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code
```
### Build a custom template
Building a custom template requires [Docker Desktop](https://docs.docker.com/desktop/).
Write a Dockerfile that extends one of the base images. Pick the variant that
matches the agent you plan to run. For example, extend `claude-code` to
customize a Claude Code environment, or `codex` to customize an OpenAI Codex
environment.
The following example creates a Claude Code template with Rust and
protocol buffer tools pre-installed:
```dockerfile
FROM docker/sandbox-templates:claude-code
USER root
RUN apt-get update && apt-get install -y protobuf-compiler
USER agent
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
```
Use `root` for system-level package installations (`apt-get`), and switch back
to `agent` before installing user-level tools. Tools that install into the
home directory, such as `rustup`, `nvm`, or `pyenv`, must run as `agent` —
otherwise they install under `/root/` and aren't available in the sandbox.
Build the image and push it to an OCI registry, such as Docker Hub:
```console
$ docker build -t my-org/my-template:v1 --push .
```
> [!NOTE]
> The Docker daemon used by Docker Sandboxes pulls templates from a registry
> directly; it doesn't share the image store of your local Docker daemon on
> the host.
Unless you use the permissive `allow-all` network policy, you may also need to
allow-list any domains that your custom tools depend on:
```console
$ sbx policy allow network "*.example.com:443,example.com:443"
```
Then run a sandbox with your template. The agent you specify must match the
base image variant your template extends:
```console
$ sbx run --template docker.io/my-org/my-template:v1 claude
```
Because this template extends the `claude-code` base image, you run it with
`claude`. If you extend `codex`, use `codex`; if you extend `shell`, use
`shell` (which drops you into a Bash shell with no agent).
> [!NOTE]
> Unlike Docker commands, `sbx` does not automatically resolve the Docker Hub
> domain (`docker.io`) in image references.
### Template caching
Template images are cached locally. The first use pulls from the registry;
subsequent sandboxes reuse the cache. Cached images persist across sandbox
creation and deletion, and are cleared when you run `sbx reset`.

72
content/manuals/ai/sandboxes/agents/docker-agent.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Docker Agent
weight: 70
description: |
Use Docker Agent in Docker Sandboxes with multi-provider authentication
supporting OpenAI, Anthropic, and more.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Official documentation: [Docker Agent](https://docs.docker.com/ai/docker-agent/)
## Quick start
Create a sandbox and run Docker Agent for a project directory:
```console
$ sbx run docker-agent ~/my-project
```
The workspace parameter defaults to the current directory, so
`sbx run docker-agent` from inside your project works too.
## Authentication
Docker Agent supports multiple providers. Store keys for the providers you want
to use with [stored secrets](../security/credentials.md#stored-secrets):
```console
$ sbx secret set -g openai
$ sbx secret set -g anthropic
$ sbx secret set -g google
$ sbx secret set -g xai
$ sbx secret set -g nebius
$ sbx secret set -g mistral
```
You only need to configure the providers you want to use. Docker Agent detects
available credentials and routes requests to the appropriate provider.
Alternatively, export the environment variables (`OPENAI_API_KEY`,
`ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `NEBIUS_API_KEY`,
`MISTRAL_API_KEY`) in your shell before running the sandbox. See
[Credentials](../security/credentials.md) for details on both methods.
## Configuration
Sandboxes don't pick up user-level configuration from your host. Only
project-level configuration in the working directory is available inside the
sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
The sandbox runs Docker Agent without approval prompts by default. Pass
additional CLI options after `--`:
```console
$ sbx run docker-agent --name my-sandbox -- <options>
```
For example, to specify a custom `agent.yml` configuration file:
```console
$ sbx run docker-agent -- agent.yml
```
## Base image
The sandbox uses `docker/sandbox-templates:docker-agent` and launches Docker
Agent without approval prompts by default. See
[Custom environments](custom-environments.md) to build your own image on top of
this base.

75
content/manuals/ai/sandboxes/agents/gemini.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: Gemini
weight: 40
description: |
Use Google Gemini in Docker Sandboxes with proxy-managed authentication and
API key configuration.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This guide covers authentication, configuration, and usage of Google Gemini in
a sandboxed environment.
Official documentation: [Gemini CLI](https://geminicli.com/docs/)
## Quick start
Create a sandbox and run Gemini for a project directory:
```console
$ sbx run gemini ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ sbx run gemini
```
## Authentication
Gemini requires either a Google API key or a Google account with Gemini access.
**API key**: Store your key using
[stored secrets](../security/credentials.md#stored-secrets):
```console
$ sbx secret set -g google
```
Alternatively, export the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment
variable in your shell before running the sandbox. See
[Credentials](../security/credentials.md) for details on both methods.
**Google account**: If no API key is set, Gemini prompts you to sign in
interactively when it starts. Interactive authentication is scoped to the
sandbox and doesn't persist if you remove and recreate it.
## Configuration
Sandboxes don't pick up user-level configuration from your host, such as
`~/.gemini`. Only project-level configuration in the working directory is
available inside the sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
The sandbox runs Gemini without approval prompts by default and disables
Gemini's built-in sandbox tool (since the sandbox itself provides isolation).
Pass additional Gemini CLI options after `--`:
```console
$ sbx run gemini --name <sandbox-name> -- <gemini-options>
```
## Base image
Template: `docker/sandbox-templates:gemini`
Gemini is configured to disable its built-in OAuth flow. Authentication is
managed through the proxy with API keys. Preconfigured to run without
approval prompts.
See [Custom environments](custom-environments.md) to pre-install tools or
customize this environment.

98
content/manuals/ai/sandboxes/agents/kiro.md Normal file
View File

@@ -0,0 +1,98 @@
---
title: Kiro
weight: 50
description: |
Use Kiro in Docker Sandboxes with device flow authentication for interactive
AI-assisted development.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This guide covers authentication, configuration, and usage of Kiro in a
sandboxed environment.
Official documentation: [Kiro CLI](https://kiro.dev/docs/cli/)
## Quick start
Create a sandbox and run Kiro for a project directory:
```console
$ sbx run kiro ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ sbx run kiro
```
On first run, Kiro prompts you to authenticate using device flow.
## Authentication
Kiro uses device flow authentication, which requires interactive login through
a web browser. This method provides secure authentication without storing API
keys directly.
### Device flow login
When you first run Kiro, it prompts you to authenticate:
1. Kiro displays a URL and a verification code
2. Open the URL in your web browser
3. Enter the verification code
4. Complete the authentication flow in your browser
5. Return to the terminal - Kiro proceeds automatically
The authentication session is persisted in the sandbox and doesn't require
repeated login unless you destroy and recreate the sandbox.
### Manual login
You can trigger the login flow manually:
```console
$ sbx run kiro --name <sandbox-name> -- login --use-device-flow
```
This command initiates device flow authentication without starting a coding
session.
### Authentication persistence
Kiro stores authentication state in `~/.local/share/kiro-cli/data.sqlite3`
inside the sandbox. This database persists as long as the sandbox exists. If
you destroy the sandbox, you'll need to authenticate again when you recreate
it.
## Configuration
Sandboxes don't pick up user-level configuration from your host. Only
project-level configuration in the working directory is available inside the
sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
Kiro requires minimal configuration. The agent runs with trust-all-tools mode
by default, which lets it execute commands without repeated approval
prompts.
### Pass options at runtime
Pass Kiro CLI options after `--`:
```console
$ sbx run kiro --name <sandbox-name> -- <kiro-options>
```
## Base image
Template: `docker/sandbox-templates:kiro`
Preconfigured to run without approval prompts. Authentication state is
persisted across sandbox restarts.
See [Custom environments](custom-environments.md) to pre-install tools or
customize this environment.

86
content/manuals/ai/sandboxes/agents/opencode.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: OpenCode
weight: 60
description: |
Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI
interface for AI development.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This guide covers authentication, configuration, and usage of OpenCode in a
sandboxed environment.
Official documentation: [OpenCode](https://opencode.ai/docs)
## Quick start
Create a sandbox and run OpenCode for a project directory:
```console
$ sbx run opencode ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ sbx run opencode
```
OpenCode launches a TUI (text user interface) where you can select your
preferred LLM provider and interact with the agent.
## Authentication
OpenCode supports multiple providers. Store keys for the providers you want to
use with [stored secrets](../security/credentials.md#stored-secrets):
```console
$ sbx secret set -g openai
$ sbx secret set -g anthropic
$ sbx secret set -g google
$ sbx secret set -g xai
$ sbx secret set -g groq
$ sbx secret set -g aws
```
You only need to configure the providers you want to use. OpenCode detects
available credentials and offers those providers in the TUI.
You can also use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
`GOOGLE_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `AWS_ACCESS_KEY_ID`). See
[Credentials](../security/credentials.md) for details on both methods.
## Configuration
Sandboxes don't pick up user-level configuration from your host. Only
project-level configuration in the working directory is available inside the
sandbox. See
[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
for workarounds.
OpenCode uses a TUI interface and doesn't require extensive configuration
files. The agent prompts you to select a provider when it starts, and you can
switch providers during a session.
### TUI mode
OpenCode launches in TUI mode by default. The interface shows:
- Available LLM providers (based on configured credentials)
- Current conversation history
- File operations and tool usage
- Real-time agent responses
Use keyboard shortcuts to navigate the interface and interact with the agent.
## Base image
Template: `docker/sandbox-templates:opencode`
OpenCode supports multiple LLM providers with automatic credential injection
through the sandbox proxy.
See [Custom environments](custom-environments.md) to pre-install tools or
customize this environment.

69
content/manuals/ai/sandboxes/architecture.md Normal file
View File

@@ -0,0 +1,69 @@
---
title: Architecture
weight: 40
description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
This page explains how Docker Sandboxes work under the hood. For the security
properties of the architecture, see [Sandbox isolation](security/isolation.md).
## Workspace mounting
Your workspace is mounted directly into the sandbox through a filesystem
passthrough. The sandbox sees your actual host files, so changes in either
direction are instant with no sync process involved.
Your workspace is mounted at the same absolute path as on your host. Preserving
absolute paths means error messages, configuration files, and build outputs all
reference paths you can find on your host. The agent sees exactly the directory
structure you see, which reduces confusion when debugging or reviewing changes.
## Storage and persistence
When you create a sandbox, everything inside it persists until you remove it:
Docker images and containers built or pulled by the agent, installed packages,
agent state and history, and workspace changes.
Sandboxes are isolated from each other. Each one maintains its own Docker
daemon state, image cache, and package installations. Multiple sandboxes don't
share images or layers.
Each sandbox consumes disk space for its VM image, Docker images, container
layers, and volumes, and this grows as you build images and install packages.
## Networking
All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on
your host. Agents are configured to use the proxy automatically. The proxy
enforces [network access policies](security/policy.md) and handles
[credential injection](security/credentials.md). See
[Network isolation](security/isolation.md#network-isolation) for how this
works and [Default security posture](security/defaults.md) for what is
allowed out of the box.
## Lifecycle
`sbx run` initializes a VM with a workspace for a specified agent and starts
the agent. You can stop and restart without recreating the VM, preserving
installed packages and Docker images.
Sandboxes persist until explicitly removed. Stopping an agent doesn't delete
the VM; environment setup carries over between runs. Use `sbx rm` to delete
the sandbox, its VM, and all of its contents. If the sandbox used
`--branch`, the worktree directories and their branches are also removed.
## Comparison to alternatives
| Approach | Isolation | Docker access | Use case |
| --------------------------------------------------- | -------------------- | ------------------ | ------------------ |
| Sandboxes (microVMs) | Full (hypervisor) | Isolated daemon | Autonomous agents |
| Container with socket mount | Partial (namespaces) | Shared host daemon | Trusted tools |
| [Docker-in-Docker](https://hub.docker.com/_/docker) | Partial (privileged) | Nested daemon | CI/CD pipelines |
| Host execution | None | Host daemon | Manual development |
Sandboxes trade higher resource overhead (a VM plus its own daemon) for
complete isolation. Use containers when you need lightweight packaging without
Docker access. Use sandboxes when you need to give something autonomous full
Docker capabilities without trusting it with your host environment.

31
content/manuals/ai/sandboxes/docker-desktop.md
View File

@@ -13,7 +13,7 @@ convenience integration with limited features compared to the standalone
sandbox CLI.
> [!NOTE]
> The standalone `ds` CLI provides more features, more flexibility, and doesn't
> The standalone `sbx` CLI provides more features, more flexibility, and doesn't
> require Docker Desktop. If you're setting up sandboxed agents for the first
> time, consider using the standalone CLI instead.
@@ -47,16 +47,16 @@ Replace `claude` with a different [agent](#supported-agents) if needed.
## Supported agents
| Agent | Command | Notes |
| --------------------------------- | ---------- | ------------------------------------ |
| Claude Code | `claude` | Most tested implementation |
| Codex | `codex` | |
| Copilot | `copilot` | |
| Gemini | `gemini` | |
| [Docker Agent](/ai/docker-agent/) | `cagent` | Also available as a standalone tool |
| Kiro | `kiro` | |
| OpenCode | `opencode` | |
| Custom shell | `shell` | Minimal environment for manual setup |
| Agent | Command | Notes |
| --------------------------------- | -------------- | ------------------------------------ |
| Claude Code | `claude` | Most tested implementation |
| Codex | `codex` | |
| Copilot | `copilot` | |
| Gemini | `gemini` | |
| [Docker Agent](/ai/docker-agent/) | `docker-agent` | Also available as a standalone tool |
| Kiro | `kiro` | |
| OpenCode | `opencode` | |
| Custom shell | `shell` | Minimal environment for manual setup |
All agents are experimental. The agent type is specified when creating a
sandbox and can't be changed later.
@@ -110,9 +110,12 @@ $ docker sandbox run <name> -- --continue
## Architecture
Each sandbox is a lightweight microVM with its own kernel, using your system's
native virtualization (macOS virtualization.framework, Windows Hyper-V). Every
sandbox includes a private Docker daemon, so `docker build` and
`docker compose up` run inside the sandbox without affecting your host.
native virtualization (macOS virtualization.framework, Windows Hyper-V). The
default agent templates include a private Docker daemon, so `docker build` and
`docker compose up` run inside the sandbox without affecting your host. On
Windows, the Docker daemon is not included by default. See
[Troubleshooting](troubleshooting.md#docker-not-available-inside-the-sandbox-on-windows)
for a workaround.
```plaintext
Host system

104
content/manuals/ai/sandboxes/faq.md Normal file
View File

@@ -0,0 +1,104 @@
---
title: FAQ
weight: 70
description: Frequently asked questions about Docker Sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
## Why do I need to sign in?
Docker Sandboxes is built around the idea that you and your agents are a team.
Signing in gives each sandbox a verified identity, which lets Docker:
- **Tie sandboxes to a real person.** Governance matters when agents can build
containers, install packages, and push code. Your Docker identity is the
anchor.
- **Enable team features down the road.** Shared environments, org-level
policies, audit logs. These all need a concept of "who," and building that in
later would be worse for everyone.
- **Authenticate against Docker infrastructure.** Sandboxes pull images, run
daemons, and talk to Docker services. A Docker account makes that seamless.
Your Docker account email is only used for authentication, not marketing.
## Does the CLI collect telemetry?
The `sbx` CLI collects basic usage data about CLI invocations:
- Which subcommand you ran
- Whether it succeeded or failed
- How long it took
- If you're signed in, your Docker username is included
Docker Sandboxes doesn't monitor sessions, read your prompts, or access your
code. Your code stays in the sandbox and on your host.
To opt out of all analytics, set the `SBX_NO_TELEMETRY` environment variable:
```console
$ export SBX_NO_TELEMETRY=1
```
## How do I set custom environment variables inside a sandbox?
The [`sbx secret`](/reference/cli/sbx/secret/) command only supports a fixed set
of [services](security/credentials.md#supported-services) (Anthropic, OpenAI,
GitHub, and others). If your agent needs an environment variable that isn't
tied to a supported service, such as `BRAVE_API_KEY` or a custom internal
token, write it to `/etc/sandbox-persistent.sh` inside the sandbox. This
file is sourced on every shell login, so the variable persists across agent
sessions for the sandbox's lifetime.
Use `sbx exec` to append the export:
```console
$ sbx exec -d <sandbox-name> bash -c "echo 'export BRAVE_API_KEY=your_key' >> /etc/sandbox-persistent.sh"
```
The `bash -c` wrapper is required so the `>>` redirect runs inside the
sandbox instead of on your host.
> [!NOTE]
> Unlike `sbx secret`, which injects credentials through a host-side proxy
> without exposing them to the agent, this approach stores the value inside
> the sandbox. The agent process can read it directly. Only use this for
> credentials where proxy-based injection isn't available.
To verify the variable is set, open a shell in the sandbox:
```console
$ sbx exec -it <sandbox-name> bash
$ echo $BRAVE_API_KEY
```
## How do I know if my agent is running in a sandbox?
Ask the agent. The agent can see whether or not it's running inside a sandbox.
In Claude Code, use the `/btw` slash command to ask without interrupting an
in-progress task:
```text
/btw are you running in a sandbox?
```
## Why doesn't the sandbox use my user-level agent configuration?
Sandboxes don't pick up user-level agent configuration from your host. This
includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex,
where hooks, skills, and other settings are stored. Only project-level
configuration in the working directory is available inside the sandbox.
To make configuration available in a sandbox, copy or move what you need into
your project directory before starting a session:
```console
$ cp -r ~/.claude/skills .claude/skills
```
Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside
the sandbox.
Collocating skills and other agent configuration with the project itself is a
good practice regardless of sandboxes. It's versioned alongside the code and
evolves with the project as it changes.

110
content/manuals/ai/sandboxes/get-started.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: Get started with Docker Sandboxes
linkTitle: Get started
weight: 10
description: Install the sbx CLI and run an AI coding agent in an isolated sandbox.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
sandbox gets its own Docker daemon, filesystem, and network — the agent can
build containers, install packages, and modify files without touching your host
system.
## Prerequisites
- macOS (Apple silicon) or Windows (x86_64, Windows 11 required)
- If you're on Windows, enable Windows Hypervisor Platform (requires
elevated permissions):
```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, and [Credentials](security/credentials.md) for how to store
and manage keys.
Docker Desktop is not required to use `sbx`.
## Install and sign in
{{< tabs >}}
{{< tab name="macOS" >}}
```console
$ brew install docker/tap/sbx
$ sbx login
```
{{< /tab >}}
{{< tab name="Windows" >}}
```powershell
> winget install -h Docker.sbx
> sbx login
```
{{< /tab >}}
{{< /tabs >}}
`sbx login` opens a browser for Docker OAuth. On first login (and after `sbx
policy reset`), the CLI prompts you to choose a default network policy for your
sandboxes:
```plaintext
Choose a default 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.
Use ↑/↓ to navigate, Enter to select, or press 1–3.
```
See [Policies](security/policy.md) for a full description of each option.
> [!NOTE]
> See the [FAQ](faq.md) for details on why sign-in is required and what
> happens with your data.
## Run your first sandbox
Pick a project directory and launch an agent with [`sbx run`](/reference/cli/sbx/run/):
```console
$ cd ~/my-project
$ sbx run claude
```
Replace `claude` with the agent you want to use — see [Agents](agents/) for the
full list.
The first run takes a little longer while the agent image is pulled.
Subsequent runs reuse the cached image and start in seconds.
You can check what's running at any time:
```console
$ sbx ls
NAME STATUS UPTIME
claude-my-project running 12s
```
The agent can modify files in your project directory, so review changes before
merging. See [Workspace trust](security/workspace.md) for details.
> [!CAUTION]
> Your network policy controls what the sandbox can reach. With **Locked
> Down**, even your model provider API is blocked. With **Balanced**, a broad
> set of common development services is allowed by default — add other hosts
> with `sbx policy allow`. See [Policies](security/policy.md) for details.
## Next steps
- [Usage guide](usage.md) — common patterns and workflows
- [Agents](agents/) — supported agents and configuration
- [Custom environments](agents/custom-environments.md) — build your own sandbox
images
- [Policies](security/policy.md) — control outbound access

BIN
content/manuals/ai/sandboxes/images/sbx-security.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 118 KiB

91
content/manuals/ai/sandboxes/security/_index.md Normal file
View File

@@ -0,0 +1,91 @@
---
title: Security model
linkTitle: Security model
weight: 50
description: Trust boundaries, isolation layers, and security properties of Docker Sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Docker Sandboxes run AI agents in microVMs so they can execute code, install
packages, and use tools without accessing your host system. Multiple isolation
layers protect your host system.
## Trust boundaries
The primary trust boundary is the microVM. The agent has full control inside
the VM, including sudo access. The VM boundary prevents the agent from reaching
anything on your host except what is explicitly shared.
What crosses the boundary into the VM:
- **Workspace directory:** mounted into the VM with read-write access. With
the default direct mount, changes the agent makes appear on your host
immediately.
- **Credentials:** the host-side proxy injects authentication headers into
outbound HTTP requests. The raw credential values never enter the VM.
- **Network access:** HTTP and HTTPS requests to
[allowed domains](defaults/) are proxied through the host.
What crosses the boundary back to the host:
- **Workspace file changes:** visible on your host in real time with the
default direct mount.
- **HTTP/HTTPS requests:** sent to allowed domains through the host proxy.
Everything else is blocked. The agent cannot access your host filesystem
(outside the workspace), your host Docker daemon, your host network or
localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP,
and ICMP are blocked at the network layer.
![Sandbox security model showing the hypervisor boundary between the sandbox VM and the host system. The workspace directory is shared read-write. The agent process, Docker engine, packages, and VM filesystem are inside the VM. Host filesystem, processes, Docker engine, and network are outside the VM and not accessible. A proxy enforces allow/deny policies and injects credentials into outbound requests.](../images/sbx-security.png)
## Isolation layers
The sandbox security model has four layers. See
[Isolation layers](isolation/) for technical details on each.
- **Hypervisor isolation:** separate kernel per sandbox. No shared memory or
processes with the host.
- **Network isolation:** all HTTP/HTTPS traffic proxied through the host.
[Deny-by-default policy](defaults/). Non-HTTP protocols blocked entirely.
- **Docker Engine isolation:** each sandbox has its own Docker Engine with no
path to the host daemon.
- **Credential isolation:** API keys are injected into HTTP headers by the
host-side proxy. Credential values never enter the VM.
## What the agent can do inside the sandbox
Inside the VM, the agent has full privileges: sudo access, package installation,
a private Docker Engine, and read-write access to the workspace. Installed
packages, Docker images, and other VM state persist across restarts. See
[Default security posture](defaults/) for the full breakdown of what is
permitted and what is blocked.
## What is not isolated by default
The sandbox isolates the agent from your host system, but the agent's actions
can still affect you through the shared workspace and allowed network channels.
**Workspace changes are live on your host.** The agent edits the same files you
see on your host. This includes files that execute implicitly during normal
development: Git hooks, CI configuration, IDE task configs, `Makefile`,
`package.json` scripts, and similar build files. Review changes before running
any modified code. Note that Git hooks live inside `.git/` and do not appear in
`git diff` output. Check them separately.
See [Workspace trust](workspace/).
**Default allowed domains include broad wildcards.** Some defaults like
`*.googleapis.com` cover many services beyond AI APIs. Run `sbx policy ls` to
see the full list of active rules, and remove entries you don't need. See
[Default security posture](defaults/).
## Learn more
- [Isolation layers](isolation/): how hypervisor, network, Docker, and
credential isolation work
- [Default security posture](defaults/): what a fresh sandbox permits and
blocks
- [Credentials](credentials/): how to provide and manage API keys
- [Policies](policy/): how to customize network access rules
- [Workspace trust](workspace/): what to review after an agent session

147
content/manuals/ai/sandboxes/security/credentials.md Normal file
View File

@@ -0,0 +1,147 @@
---
title: Credentials
weight: 20
description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Most agents need an API key for their model provider. An HTTP/HTTPS proxy on
your host intercepts outbound API requests from the sandbox and injects the
appropriate authentication headers before forwarding each request. Your
credentials stay on the host and are never stored inside the sandbox VM. For
how this works as a security layer, see
[Credential isolation](isolation.md#credential-isolation).
There are two ways to provide credentials:
- **Stored secrets** (recommended): saved in your OS keychain, encrypted and
persistent across sessions.
- **Environment variables:** read from your current shell session. This works
but is less secure on the host side, since environment variables are visible
to other processes running as your user.
If both are set for the same service, the stored secret takes precedence. For
multi-provider agents (OpenCode, Docker Agent), the proxy automatically selects the
correct credentials based on the API endpoint being called. See individual
[agent pages](../agents/) for provider-specific details.
## Stored secrets
The `sbx secret` command stores credentials in your OS keychain so you don't
need to export environment variables in every terminal session. When a sandbox
starts, the proxy looks up stored secrets and uses them to authenticate API
requests on behalf of the agent. The secret is never exposed directly to the
agent.
### Store a secret
```console
$ sbx secret set -g anthropic
```
This prompts you for the secret value interactively. The `-g` flag stores the
secret globally so it's available to all sandboxes. To scope a secret to a
specific sandbox instead:
```console
$ sbx secret set my-sandbox openai
```
> [!NOTE]
> A sandbox-scoped secret takes effect immediately, even if the sandbox is
> running. A global secret (`-g`) only applies when a sandbox is created. If
> you set or change a global secret while a sandbox is running, recreate the
> sandbox for the new value to take effect.
You can also pipe in a value for non-interactive use:
```console
$ echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic
```
### Supported services
Each service name maps to a set of environment variables the proxy checks and
the API domains it authenticates requests to:
| Service | Environment variables | API domains |
| ----------- | -------------------------------------------- | ----------------------------------- |
| `anthropic` | `ANTHROPIC_API_KEY` | `api.anthropic.com` |
| `aws` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | AWS Bedrock endpoints |
| `github` | `GH_TOKEN`, `GITHUB_TOKEN` | `api.github.com`, `github.com` |
| `google` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `generativelanguage.googleapis.com` |
| `groq` | `GROQ_API_KEY` | `api.groq.com` |
| `mistral` | `MISTRAL_API_KEY` | `api.mistral.ai` |
| `nebius` | `NEBIUS_API_KEY` | `api.studio.nebius.ai` |
| `openai` | `OPENAI_API_KEY` | `api.openai.com` |
| `xai` | `XAI_API_KEY` | `api.x.ai` |
When you store a secret with `sbx secret set -g <service>`, the proxy uses it
the same way it would use the corresponding environment variable. You don't
need to set both.
### List and remove secrets
List all stored secrets:
```console
$ sbx secret ls
SCOPE SERVICE SECRET
(global) github gho_GCaw4o****...****43qy
```
Remove a secret:
```console
$ sbx secret rm -g github
```
> [!NOTE]
> Running `sbx reset` deletes all stored secrets along with all sandbox state.
> You'll need to re-add your secrets after a reset.
### GitHub token
The `github` service gives the agent access to the `gh` CLI inside the
sandbox. Pass your existing GitHub CLI token:
```console
$ echo "$(gh auth token)" | sbx secret set -g github
```
This is useful for agents that create pull requests, open issues, or interact
with GitHub APIs on your behalf.
## Environment variables
As an alternative to stored secrets, export the relevant environment variable
in your shell before running a sandbox:
```console
$ export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
$ sbx run claude
```
The proxy reads the variable from your terminal session. See individual
[agent pages](../agents/) for the variable names each agent expects.
## Best practices
- Use [stored secrets](#stored-secrets) over environment variables. The OS
keychain encrypts credentials at rest and controls access, while environment
variables are plaintext in your shell.
- Don't set API keys manually inside the sandbox. Credentials stored in
environment variables or configuration files inside the VM are readable by
the agent process directly.
- For Claude Code, the interactive OAuth flow is another secure option: the
proxy handles authentication without exposing the token inside the sandbox.
Leave `ANTHROPIC_API_KEY` unset to use OAuth.
## Custom templates and placeholder values
When building custom templates or installing agents manually in a shell
sandbox, some agents require environment variables like `OPENAI_API_KEY` to be
set before they start. Set these to placeholder values (e.g. `proxy-managed`)
if needed. The proxy injects actual credentials regardless of the environment
variable value.

68
content/manuals/ai/sandboxes/security/defaults.md Normal file
View File

@@ -0,0 +1,68 @@
---
title: Default security posture
linkTitle: Defaults
weight: 15
description: What a sandbox permits and blocks before you change any settings.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
A sandbox created with `sbx run` and no additional flags or blueprints has
the following security posture.
## Network defaults
All outbound HTTP and HTTPS traffic is blocked unless an explicit rule allows
it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and
ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback
addresses, and link-local addresses is also blocked.
Run `sbx policy ls` to see the active allow rules for your installation. To
customize network access, see [Policies](policy.md).
## Workspace defaults
Sandboxes use a direct mount by default. The agent sees and modifies your
working tree directly, and changes appear on your host immediately.
The agent can read, write, and delete any file within the workspace directory,
including hidden files, configuration files, build scripts, and Git hooks.
See [Workspace trust](workspace.md) for what to review after an agent session.
## Credential defaults
No credentials are available to the sandbox unless you provide them using
`sbx secret` or environment variables. When credentials are provided, the
host-side proxy injects them into outbound HTTP headers. The agent cannot
read the raw credential values.
See [Credentials](credentials.md) for setup instructions.
## Agent capabilities inside the sandbox
The agent runs with full control inside the sandbox VM:
- `sudo` access (the agent runs as a non-root user with sudo privileges)
- A private Docker Engine for building images and running containers
- Package installation through `apt`, `pip`, `npm`, and other package managers
- Full read and write access to the VM filesystem
Everything the agent installs or creates inside the VM, including packages,
Docker images, and configuration changes, persists across stop and restart
cycles. When you remove the sandbox with `sbx rm`, the VM and its contents
are deleted. Only workspace files remain on the host.
## What is blocked by default
The following are blocked for all sandboxes and cannot be changed through
policy configuration:
- Host filesystem access outside the workspace directory
- Host Docker daemon
- Host network and localhost
- Communication between sandboxes
- Raw TCP, UDP, and ICMP connections
- Traffic to private IP ranges and link-local addresses
Outbound HTTP/HTTPS to domains not in the allow list is also blocked by
default, but you can add allow rules with `sbx policy allow`.

86
content/manuals/ai/sandboxes/security/isolation.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Isolation layers
weight: 10
description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, and credential boundaries.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
AI coding agents need to execute code, install packages, and run tools on
your behalf. Docker Sandboxes run each agent in its own microVM with four
isolation layers: hypervisor, network, Docker Engine, and credential proxy.
## Hypervisor isolation
Every sandbox runs inside a lightweight microVM with its own Linux kernel.
Unlike containers, which share the host kernel, a sandbox VM cannot access host
processes, files, or resources outside its defined boundaries.
- **Process isolation:** separate kernel per sandbox; processes inside the VM
are invisible to your host and to other sandboxes
- **Filesystem isolation:** only your workspace directory is shared with the
host. The rest of the VM filesystem persists across restarts but is removed
when you delete the sandbox. Symlinks pointing outside the workspace scope
are not followed.
- **Full cleanup:** when you remove a sandbox with `sbx rm`, the VM and
everything inside it is deleted
The agent runs as a non-root user with sudo privileges inside the VM. The
hypervisor boundary is the isolation control, not in-VM privilege separation.
## Network isolation
Each sandbox has its own isolated network. Sandboxes cannot communicate with
each other and cannot reach your host's localhost. There is no shared network
between sandboxes or between a sandbox and your host.
All HTTP and HTTPS traffic leaving a sandbox passes through a proxy on your
host that enforces the [network policy](policy.md). The sandbox routes
traffic through either a forward proxy or a transparent proxy depending on the
client's configuration. Both enforce the network policy; only the forward proxy
[injects credentials](credentials.md) for AI services.
Raw TCP connections, UDP, and ICMP are blocked at the network layer. DNS
resolution is handled by the proxy; the sandbox cannot make raw DNS queries.
Traffic to private IP ranges, loopback, and link-local addresses is also
blocked. Only domains explicitly listed in the policy are reachable.
For the default set of allowed domains, see
[Default security posture](defaults.md).
## Docker Engine isolation
Agents often need to build images, run containers, and use Docker Compose.
Mounting your host Docker socket into a container would give the agent full
access to your environment.
Docker Sandboxes avoid this by running a separate [Docker
Engine](https://docs.docker.com/engine/) inside the sandbox environment, isolated from
your host. When the agent runs `docker build` or `docker compose up`, those
commands execute against that engine. The agent has no path to your host Docker
daemon.
```plaintext
Host system
├── Host Docker daemon
│ └── Your containers and images
│
└── Sandbox Docker engine (isolated from host)
├── [VM] Agent container — sandbox 1
│ └── [VM] Containers created by agent
└── [VM] Agent container — sandbox 2
└── [VM] Containers created by agent
```
## Credential isolation
Most agents need API keys for their model provider. Rather than passing keys
into the sandbox, the host-side proxy intercepts outbound API requests and
injects authentication headers before forwarding each request.
Credential values are never stored inside the VM. They are not available as
environment variables or files inside the sandbox unless you explicitly set
them. This means a compromised sandbox cannot read API keys from the local
environment.
For how to store and manage credentials, see [Credentials](credentials.md).

293
content/manuals/ai/sandboxes/security/policy.md Normal file
View File

@@ -0,0 +1,293 @@
---
title: Policies
weight: 30
description: Configure network access and filesystem rules for sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Sandboxes are [network-isolated](isolation.md) from your host and from each
other. A policy system controls what a sandbox can access — which external
hosts it can reach over the network, and which host paths it can mount as
workspaces.
Policies can be set at two levels:
- **Organization policies** {{< badge color=blue text="Limited Access" >}} — configured by admins in the
[Docker Admin Console](https://app.docker.com/admin) under AI governance
settings. These apply to all sandboxes across the organization.
- **Local policies** — configured by individual users with the `sbx policy`
command. These apply to all sandboxes on the local machine.
If your organization has enabled governance, organization policies take
precedence over local rules and can't be overridden locally. See
[Precedence](#precedence) for the full evaluation model.
## Organization policies {tier="Limited Access"}
> [!NOTE]
> Organization governance is a Limited Access feature. Contact your Docker
> account team to request access.
Organization admins can centrally manage policies through the
[Docker Admin Console](https://app.docker.com/admin). Navigate to your
organization settings and enable **Manage AI governance**.
Once enabled, the policies defined in the Admin Console apply to all
sandboxes across the organization, regardless of any local policies
configured with `sbx policy`.
### Local extensions to organization policy
Organization policy is the baseline for all sandboxes in your organization.
Admins can optionally permit users to extend it locally by enabling the
**User defined** setting in AI governance settings. When enabled, users can
add hosts to the allowlist from their own machine using `sbx policy allow network`.
Local extensions can only expand access within what the organization permits.
They can't override organization-level deny rules.
## Network policies
The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on
your host, which enforces access rules on every outbound request.
### Initial policy selection
On first start, and after running `sbx policy reset`, the daemon prompts you to
choose a network policy:
```plaintext
Choose a default 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.
Use ↑/↓ to navigate, Enter to select, or press 1–3.
```
| Policy | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. |
| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. You can extend this with `sbx policy allow`. |
| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. |
You can change your effective policy at any time using `sbx policy allow` and
`sbx policy deny`, or start over by running `sbx policy reset`.
### Non-interactive environments
In non-interactive environments such as CI pipelines or headless servers, the
interactive prompt can't be displayed. Use `sbx policy set-default` to set the
default network policy before running any other `sbx` commands:
```console
$ sbx policy set-default balanced
```
Available values are `allow-all`, `balanced`, and `deny-all`. After setting the
default, you can customize further with `sbx policy allow` and
`sbx policy deny` as usual.
### Default policy
All outbound HTTP/HTTPS traffic is blocked by default unless an explicit rule
allows it. The **Balanced** policy ships with a baseline allowlist covering AI provider
APIs, package managers, code hosts, container registries, and common cloud
services. Run `sbx policy ls` to see the active rules for your installation.
Organization admins can modify or remove these defaults when configuring
[organization policies](#organization-policies).
### Managing local rules
Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and
[`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add network access
rules. Changes take effect immediately and apply to all sandboxes:
```console
$ sbx policy allow network api.anthropic.com
$ sbx policy deny network ads.example.com
```
Specify multiple hosts in one command with a comma-separated list:
```console
$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"
```
List all active policy rules with `sbx policy ls`:
```console
$ sbx policy ls
ID TYPE DECISION RESOURCES
a1b2c3d4-e5f6-7890-abcd-ef1234567890 network allow api.anthropic.com, *.npmjs.org
f9e8d7c6-b5a4-3210-fedc-ba0987654321 network deny ads.example.com
```
Use `--type network` to show only network policies.
Remove a policy by resource or by rule ID:
```console
$ sbx policy rm network --resource ads.example.com
$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
```
### Resetting to defaults
To remove all custom policies and restore the default policy, use
`sbx policy reset`:
```console
$ sbx policy reset
```
This deletes the local policy store and stops the daemon. When the daemon
restarts on the next command, you are prompted to choose a new network policy.
If sandboxes are running, they stop when the daemon shuts down. You are prompted for
confirmation unless you pass `--force`:
```console
$ sbx policy reset --force
```
### Switching to allow-by-default
If you prefer a permissive policy where all outbound traffic is allowed, add
a wildcard allow rule:
```console
$ sbx policy allow network "**"
```
This lets agents install packages and call any external API without additional
configuration. You can still deny specific hosts with `sbx policy deny`.
### Org-level rules {tier="Limited Access"}
Define network allow and deny rules in the Admin Console under
**AI governance > Network access**. Each rule takes a network target (domain,
wildcard, or CIDR range) and an action (allow or deny). You can add multiple
entries at once, one per line.
Organization-level rules use the same [wildcard syntax](#wildcard-syntax) as
local rules.
### Wildcard syntax
Rules support exact domains (`example.com`), wildcard subdomains
(`*.example.com`), and optional port suffixes (`example.com:443`).
Note that `example.com` doesn't match subdomains, and `*.example.com` doesn't
match the root domain. Specify both to cover both.
### Common patterns
Allow access to package managers so agents can install dependencies:
```console
$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"
```
The **Balanced** policy already includes AI provider APIs, package managers,
code hosts, and container registries. You only need to add allow rules for
additional domains your workflow requires. If you chose **Locked Down**, you
must explicitly allow everything.
> [!WARNING]
> Allowing broad domains like `github.com` permits access to any content on
> that domain, including user-generated content. Only allow domains you trust
> with your data.
### Monitoring
Use `sbx policy log` to see which hosts your sandboxes have contacted:
```console
$ sbx policy log
Blocked requests:
SANDBOX TYPE HOST PROXY RULE LAST SEEN COUNT
my-sandbox network blocked.example.com transparent policykit 10:15:25 29-Jan 1
Allowed requests:
SANDBOX TYPE HOST PROXY RULE LAST SEEN COUNT
my-sandbox network api.anthropic.com forward policykit 10:15:23 29-Jan 42
my-sandbox network registry.npmjs.org transparent policykit 10:15:20 29-Jan 18
```
The **PROXY** column shows how the request left the sandbox:
| Value | Description |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `forward` | Routed through the forward proxy. Supports [credential injection](credentials.md). |
| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. |
| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). Always blocked. |
Filter by sandbox name by passing it as an argument:
```console
$ sbx policy log my-sandbox
```
Use `--limit N` to show only the last `N` entries, `--json` for
machine-readable output, or `--type network` to filter by policy type.
## Filesystem policies
Filesystem policies control which host paths a sandbox can mount as
workspaces. By default, sandboxes can mount any directory the user has
access to.
### Org-level restrictions {tier="Limited Access"}
Admins can restrict which paths are mountable by defining filesystem allow
and deny rules in the Admin Console under **AI governance > Filesystem access**.
Each rule takes a path pattern and an action (allow or deny).
> [!CAUTION]
> Use `**` (double wildcard) rather than `*` (single wildcard) when writing
> path patterns to match path segments recursively. A single `*` only matches
> within a single path segment. For example, `~/**` matches all paths under the
> user's home directory, whereas `~/*` matches only paths directly under `~`.
## Precedence
Within any layer, deny rules beat allow rules — if a domain matches both,
it's blocked regardless of specificity.
Docker Sandboxes ships with a baseline allowlist (the default policies). Local
`sbx policy` rules add to this baseline. The full evaluation order when
organization policies are enabled:
1. **Organization policies** (Docker Admin Console) — highest precedence.
Organization admins can modify or replace the default allowlist and define
their own rules. Organization-level denials can't be overridden locally.
2. **Local extensions** — if the admin has enabled the **User defined**
setting, users can add allow rules with `sbx policy allow network`. These
can only expand access within what the organization permits.
3. **Local rules** (`sbx policy`) — lowest precedence. Can't override
organization-level denials.
The same model applies to filesystem policies: organization-level rules take
precedence over local behavior.
To unblock a domain, identify where the deny rule comes from. For local rules,
remove it with `sbx policy rm`. For organization-level rules, contact your
organization admin.
## Troubleshooting
### Policy changes not taking effect
If policy changes aren't taking effect, run `sbx policy reset` to wipe the
local policy store and restart the daemon. On next start, you are prompted to
choose a new network policy, and the latest organization policies are pulled if
governance is enabled.
### Sandbox cannot mount workspace
If a sandbox fails to mount with a `mount policy denied` error, verify that
the filesystem allow rule uses `**` rather than `*`. A single `*` doesn't
match across directory separators.

73
content/manuals/ai/sandboxes/security/workspace.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: Workspace trust
weight: 40
description: |
How sandboxed agents interact with your workspace files and what to review
after an agent session.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
Agents running in sandboxes have full access to the workspace directory without
prompting. With the default direct mount, changes the agent makes appear on
your host immediately. Treat sandbox-modified workspace files the same way
you would treat a pull request from an untrusted contributor: review before
you trust them on your host.
## What the agent can modify
The agent can create, modify, and delete any file in the workspace. This
includes:
- Source code files
- Configuration files (`.eslintrc`, `pyproject.toml`, `.env`, etc.)
- Build files (`Makefile`, `package.json`, `Cargo.toml`)
- Git hooks (`.git/hooks/`)
- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`)
- IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations)
- Hidden files and directories
- Shell scripts and executables
> [!CAUTION]
> Files like Git hooks, CI configuration, IDE task configs, and build scripts
> execute code when triggered by normal development actions such as committing,
> building, or opening the project in an IDE. Review these files after any agent
> session before performing those actions.
## Branch mode
The `--branch` flag lets the agent work on a separate branch. This is a
workflow convenience, not a security boundary: the agent still mounts the full
repository. See the [usage guide](../usage.md) for details.
## Reviewing changes
After an agent session, review changes before executing any code the agent
touched.
With the default direct mount, changes are in your working tree:
```console
$ git diff
```
If you used `--branch`, the agent's changes are on a separate branch:
```console
$ git diff main..my-feature
```
Pay particular attention to:
- **Git hooks** (`.git/hooks/`): run on commit, push, and other Git actions.
These are inside `.git/` and **do not appear in `git diff` output**. Check
them separately with `ls -la .git/hooks/`.
- **CI configuration** (`.github/workflows/`, `.gitlab-ci.yml`): runs on push
- **Build files** (`Makefile`, `package.json` scripts, `Cargo.toml`): run
during build or install steps
- **IDE configuration** (`.vscode/tasks.json`, `.idea/`): can run tasks when
you open the project
- **Executable files and shell scripts**: can run directly
These files execute code without you explicitly running them. Review them before
committing, building, or opening the project in an IDE.

137
content/manuals/ai/sandboxes/troubleshooting.md Normal file
View File

@@ -0,0 +1,137 @@
---
title: Troubleshooting
weight: 60
description: Resolve common issues when using Docker Sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
## Resetting sandboxes
If you hit persistent issues or corrupted state, run
[`sbx reset`](/reference/cli/sbx/reset/) to stop all VMs and delete all sandbox
data. Create fresh sandboxes afterwards.
## Agent can't install packages or reach an API
Sandboxes use a [deny-by-default network policy](security/policy.md).
If the agent fails to install packages or call an external API, the target
domain is likely not in the allow list. Check which requests are being blocked:
```console
$ sbx policy log
```
Then allow the domains your workflow needs:
```console
$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
```
To allow all outbound traffic instead:
```console
$ sbx policy allow network "**"
```
## Docker authentication failure
If you see a message like `You are not authenticated to Docker`, your login
session has expired. In an interactive terminal, the CLI prompts you to sign in
again. In non-interactive environments such as scripts or CI, run `sbx login`
to re-authenticate.
## Agent authentication failure
If the agent can't reach its model provider or you see API key errors, the key
is likely invalid, expired, or not configured. Verify it's set in your shell
configuration file and that you sourced it or opened a new terminal.
For agents that use the [credential proxy](security/credentials.md), make sure
you haven't set the API key to an invalid value inside the sandbox — the proxy
injects credentials automatically on outbound requests.
If credentials are configured correctly but API calls still fail, check
`sbx policy log` and look at the **PROXY** column. Requests routed through
the `transparent` proxy don't get credential injection. This can happen when a
client inside the sandbox (such as a process in a Docker container) isn't
configured to use the forward proxy. See
[Monitoring network activity](security/policy.md#monitoring-network-activity)
for details.
## Docker not available inside the sandbox on Windows
On Windows, sandboxes use non-docker template variants by default, so `docker`
commands aren't available inside the sandbox. To use Docker inside a sandbox on
Windows, specify a `-docker` template:
```console
$ sbx run --template docker.io/docker/sandbox-templates:claude-code-docker claude
```
The `-docker` variants work on Windows but have slower startup times. See
[Base images](agents/custom-environments.md#base-images) for details and the
full list of templates.
## Docker build export fails with "lchown: operation not permitted"
Running `docker build` with the local exporter (`--output=type=local` or `-o
<path>`) inside a sandbox fails because the exporter tries to `lchown` output
files to preserve ownership from the build. Processes inside the sandbox run as
an unprivileged user without `CAP_CHOWN`, so the operation is denied.
Use the tar exporter and extract the archive instead:
```console
$ docker build --output type=tar,dest=- . | tar xf - -C ./result
```
Extracting the tar archive as the current user avoids the `chown` call.
## Stale Git worktree after removing a sandbox
If you used `--branch`, worktree cleanup during `sbx rm` is best-effort. If
it fails, the sandbox is removed but the branch and worktree are left behind.
If `git worktree list` shows a stale worktree in `.sbx/` after removing a
sandbox, clean it up manually:
```console
$ git worktree remove .sbx/<sandbox-name>-worktrees/<branch-name>
$ git branch -D <branch-name>
```
## Clock drift after sleep/wake
If your laptop sleeps and wakes while a sandbox is running, the VM clock can
fall behind the host clock. This causes problems such as:
- External API calls failing because of timestamp validation.
- Git commits with incorrect timestamps.
- TLS certificate errors due to time mismatches.
To fix the issue, stop and restart the sandbox:
```console
$ sbx stop <sandbox-name>
$ sbx run <sandbox-name>
```
Restarting the sandbox re-syncs the VM clock with the host.
## Removing all state
As a last resort, if `sbx reset` doesn't resolve your issue, you can remove the
`sbx` state directory entirely. This deletes all sandbox data, configuration, and
cached images. Stop all running sandboxes first with `sbx reset`.
macOS:
```console
$ rm -rf ~/Library/Application\ Support/com.docker.sandboxes/
```
Windows:
```powershell
> Remove-Item -Recurse -Force "$env:LOCALAPPDATA\DockerSandboxes"
```

307
content/manuals/ai/sandboxes/usage.md Normal file
View File

@@ -0,0 +1,307 @@
---
title: Usage
weight: 20
description: Common patterns for working with sandboxes.
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
## Working with sandboxes
The basic workflow is [`run`](/reference/cli/sbx/run/) to start,
[`ls`](/reference/cli/sbx/ls/) to check status,
[`stop`](/reference/cli/sbx/stop/) to pause, and
[`rm`](/reference/cli/sbx/rm/) to clean up:
```console
$ sbx run claude # start an agent
$ sbx ls # see what's running
$ sbx stop my-sandbox # pause it
$ sbx rm my-sandbox # delete it entirely
```
To get a shell inside a running sandbox — useful for inspecting the environment,
checking Docker containers, or manually installing something:
```console
$ sbx exec -it <sandbox-name> bash
```
If you need a clean slate, remove the sandbox and re-run:
```console
$ sbx rm my-sandbox
$ sbx run claude
```
## Interactive mode
Running `sbx` with no subcommands opens an interactive terminal dashboard:
```console
$ sbx
```
The dashboard shows all your sandboxes as cards with live status, CPU, and
memory usage. From here you can:
- **Create** a sandbox (`c`).
- **Start or stop** a sandbox (`s`).
- **Attach** to an agent session (`Enter`), same as `sbx run`.
- **Open a shell** inside the sandbox (`x`), same as `sbx exec`.
- **Remove** a sandbox (`r`).
The dashboard also includes a network governance panel where you can monitor
outbound connections made by your sandboxes and manage network rules. Use `tab`
to switch between the sandboxes panel and the network panel.
From the network panel you can browse connection logs, allow or block specific
hosts, and add custom network rules. Press `?` to see all keyboard shortcuts.
## Git workflow
When your workspace is a Git repository, the agent edits your working tree
directly by default. Changes appear in your working tree immediately, the same
as working in a normal terminal.
If you run multiple agents on the same repository at once, use [branch
mode](#branch-mode) to give each agent its own branch and working directory.
### Direct mode (default)
The agent edits your working tree directly. Stage, commit, and push as you
normally would. If you run multiple agents on the same repository at the same
time, they may step on each other's changes. See
[branch mode](#branch-mode) for an alternative.
### Branch mode
Pass `--branch <name>` to give the agent its own
[Git worktree](https://git-scm.com/docs/git-worktree) and branch. This
prevents conflicts when multiple agents, or you and an agent, write to the
same files at the same time. You can set `--branch` on `create`, `run`, or
both.
The CLI creates worktrees under `.sbx/` in your repository root. The
worktree is a separate working directory, so the agent doesn't touch your main
working tree. This means:
- The worktree branches off your latest commit when you create it.
Uncommitted changes in your working tree are not included (`sbx` warns you
if it detects any).
- Files you add or change in your main working tree won't be visible to the
agent, and vice versa. The two directories are independent.
#### Starting a branch
```console
$ sbx run claude --branch my-feature # agent works on the my-feature branch
```
Use `--branch auto` to let the CLI generate a branch name for you:
```console
$ sbx run claude --branch auto
```
You can also create the sandbox first and add a branch at run time:
```console
$ sbx create --name my-sandbox claude .
$ sbx run --branch my-feature my-sandbox
```
Or set the branch at create time and reuse it on subsequent runs:
```console
$ sbx create --name my-sandbox --branch my-feature claude .
$ sbx run my-sandbox # resumes in the my-feature worktree
$ sbx run --branch my-feature my-sandbox # same — reuses the existing worktree
```
#### Multiple branches per sandbox
You can run multiple worktrees in the same sandbox by passing different branch
names:
```console
$ sbx run --branch feature-a my-sandbox
$ sbx run --branch feature-b my-sandbox
```
#### Reviewing and pushing changes
To review the agent's work, find the worktree with `git worktree list`, then
push or open a PR from there:
```console
$ git worktree list # find the worktree path
$ cd .sbx/<sandbox-name>-worktrees/my-feature
$ git log # see what the agent did
$ git push -u origin my-feature
$ gh pr create
```
Some agents don't commit automatically and leave changes uncommitted in the
worktree. If that happens, commit from the worktree directory before pushing.
See [Workspace trust](security/workspace.md) for security considerations when
reviewing agent changes.
#### Cleanup
`sbx rm` removes the sandbox and all of its worktrees and branches.
#### Ignoring the `.sbx/` directory
Branch mode stores worktrees under `.sbx/` in your repository root. To keep
this directory out of `git status`, add it to your project's `.gitignore`:
```console
$ echo '.sbx/' >> .gitignore
```
Or, to ignore it across all repositories, add `.sbx/` to your global gitignore:
```console
$ echo '.sbx/' >> "$(git config --global core.excludesFile)"
```
> [!TIP]
> If `git config --global core.excludesFile` is empty, set one first:
> `git config --global core.excludesFile ~/.gitignore`.
You can also create Git worktrees yourself and run an agent directly in one,
but the sandbox won't have access to the `.git` directory in the parent
repository. This means the agent can't commit, push, or use Git. `--branch`
solves this by setting up the worktree so that Git works inside the sandbox.
## Reconnecting and naming
Sandboxes persist after the agent exits. Running the same workspace path again
reconnects to the existing sandbox rather than creating a new one:
```console
$ sbx run claude ~/my-project # creates sandbox
$ sbx run claude ~/my-project # reconnects to same sandbox
```
Use `--name` to make this explicit and avoid ambiguity:
```console
$ sbx run claude --name my-project
```
## Creating without attaching
[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to
the agent. To create a sandbox in the background without attaching:
```console
$ sbx create claude .
```
Unlike `run`, `create` requires an explicit workspace path. It uses direct
mode by default, or pass `--branch` for [branch mode](#branch-mode). Attach
later with `sbx run`:
```console
$ sbx run claude-my-project
```
## Multiple workspaces
You can mount extra directories into a sandbox alongside the main workspace.
The first path is the primary workspace — the agent starts here, and the
sandbox's Git worktree is created from this directory if you use `--branch`.
Extra workspaces are always mounted directly.
All workspaces appear inside the sandbox at their absolute host paths. Append
`:ro` to mount an extra workspace read-only — useful for reference material or
shared libraries the agent shouldn't modify:
```console
$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro
```
Each sandbox is completely isolated, so you can also run separate projects
side-by-side. Remove unused sandboxes when you're done to reclaim disk space:
```console
$ sbx run claude ~/project-a
$ sbx run claude ~/project-b
$ sbx rm <sandbox-name> # when finished
```
## Installing dependencies and using Docker
Ask the agent to install what's needed — it has sudo access, and installed
packages persist for the sandbox's lifetime. For teams or repeated setups,
[custom templates](agents/custom-environments.md) let you pre-install tools
into a reusable image.
Agents can also build Docker images, run containers, and use
[Compose](https://docs.docker.com/compose/). Everything runs inside the sandbox's private Docker
daemon, so containers started by the agent never appear in your host's
`docker ps`. When you remove the sandbox, all images, containers, and volumes
inside it are deleted with it.
## Accessing services in the sandbox
Sandboxes are [network-isolated](security/isolation.md) — your browser or local
tools can't reach a server running inside one by default. Use
[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into
a running sandbox.
The common case: an agent has started a dev server or API, and you want to open
it in your browser or run tests against it.
```console
$ sbx ports my-sandbox --publish 8080:3000 # host 8080 → sandbox port 3000
$ open http://localhost:8080
```
To let the OS pick a free host port instead of choosing one yourself:
```console
$ sbx ports my-sandbox --publish 3000 # ephemeral host port
$ sbx ports my-sandbox # check which port was assigned
```
`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports`
lists them in detail:
```console
$ sbx ls
SANDBOX AGENT STATUS PORTS WORKSPACE
my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj
```
To stop forwarding a port:
```console
$ sbx ports my-sandbox --unpublish 8080:3000
```
A few things to keep in mind:
- **Services must bind to `0.0.0.0`** — a service listening on `127.0.0.1`
inside the sandbox won't be reachable through a published port. Most dev
servers default to `127.0.0.1`, so you'll usually need to pass a flag like
`--host 0.0.0.0` when starting them.
- **Not persistent** — published ports are lost when the sandbox stops or the
daemon restarts. Re-publish after restarting.
- **No create-time flag** — unlike `docker run -p`, there's no `--publish`
option on `sbx run` or `sbx create`. Ports can only be published after the
sandbox is running.
- **Unpublish requires the host port** — `--unpublish 3000` is rejected; you
must use `--unpublish 8080:3000`. Run `sbx ports my-sandbox` first if you
used an ephemeral port and need to find the assigned host port.
## What persists
While a sandbox exists, installed packages, Docker images, configuration
changes, and command history all persist across stops and restarts. When you
remove a sandbox, everything inside is deleted — only your workspace files
remain on your host. To preserve a configured environment, create a
[custom template](agents/custom-environments.md).

48
content/reference/cli/sbx/_content.gotmpl Normal file
View File

@@ -0,0 +1,48 @@
{{- /*
Content adapter for sbx CLI reference pages.
Generates pages from YAML data files in site.Data.sbx_cli (cobra/doc format).
For each YAML file it creates a page at the command path (spaces → slashes).
Commands with child entries in see_also become Hugo sections; others become
regular pages.
*/ -}}
{{- range $name, $data := site.Data.sbx_cli -}}
{{- if not $data.name -}}
{{- continue -}}
{{- end -}}
{{- /* Determine if this command has child commands (from see_also) */ -}}
{{- $hasChildren := false -}}
{{- $prefix := printf "%s " $data.name -}}
{{- with $data.see_also -}}
{{- range . -}}
{{- $cmd := index (split . " - ") 0 -}}
{{- if strings.HasPrefix $cmd $prefix -}}
{{- $hasChildren = true -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- /* Compute path relative to this adapter (strip "sbx/" prefix) */ -}}
{{- $fullPath := replace $data.name " " "/" -}}
{{- $kind := cond $hasChildren "section" "page" -}}
{{- if eq $data.name "sbx" -}}
{{- /* Root command is the section index */ -}}
{{- $.AddPage (dict
"path" "."
"title" $data.name
"kind" "section"
"params" (dict "datafile" $name)
) -}}
{{- else -}}
{{- $relPath := strings.TrimPrefix "sbx/" $fullPath -}}
{{- $.AddPage (dict
"path" $relPath
"title" $data.name
"kind" $kind
"params" (dict "datafile" $name)
) -}}
{{- end -}}
{{- end -}}

32
data/sbx_cli/sbx.yaml Normal file
View File

@@ -0,0 +1,32 @@
name: sbx
synopsis: Manage AI coding agent sandboxes.
description: |-
Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker.
Run without a command to launch interactive mode, or pass a command for CLI usage.
usage: sbx
options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: help
shorthand: h
default_value: "false"
usage: help for sbx
see_also:
- sbx completion - Generate the autocompletion script for the specified shell
- sbx create - Create a sandbox for an agent
- sbx exec - Execute a command inside a sandbox
- sbx login - Sign in to Docker
- sbx logout - Sign out of Docker
- sbx ls - List sandboxes
- sbx policy - Manage sandbox policies
- sbx ports - Manage sandbox port publishing
- sbx reset - Reset all sandboxes and clean up state
- sbx rm - Remove one or more sandboxes
- sbx run - Run an agent in a sandbox
- sbx save - Save a snapshot of the sandbox as a template
- sbx secret - Manage stored secrets
- sbx stop - Stop one or more sandboxes without removing them
- sbx version - Show Docker Sandboxes version information

21
data/sbx_cli/sbx_completion.yaml Normal file
View File

@@ -0,0 +1,21 @@
name: sbx completion
synopsis: Generate the autocompletion script for the specified shell
description: |
Generate the autocompletion script for sbx for the specified shell.
See each sub-command's help for details on how to use the generated script.
options:
- name: help
shorthand: h
default_value: "false"
usage: help for completion
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.
- sbx completion bash - Generate the autocompletion script for bash
- sbx completion fish - Generate the autocompletion script for fish
- sbx completion powershell - Generate the autocompletion script for powershell
- sbx completion zsh - Generate the autocompletion script for zsh

39
data/sbx_cli/sbx_completion_bash.yaml Normal file
View File

@@ -0,0 +1,39 @@
name: sbx completion bash
synopsis: Generate the autocompletion script for bash
description: |
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(sbx completion bash)
To load completions for every new session, execute once:
#### Linux:
sbx completion bash > /etc/bash_completion.d/sbx
#### macOS:
sbx completion bash > $(brew --prefix)/etc/bash_completion.d/sbx
You will need to start a new shell for this setup to take effect.
usage: sbx completion bash
options:
- name: help
shorthand: h
default_value: "false"
usage: help for bash
- name: no-descriptions
default_value: "false"
usage: disable completion descriptions
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx completion - Generate the autocompletion script for the specified shell

30
data/sbx_cli/sbx_completion_fish.yaml Normal file
View File

@@ -0,0 +1,30 @@
name: sbx completion fish
synopsis: Generate the autocompletion script for fish
description: |
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
sbx completion fish | source
To load completions for every new session, execute once:
sbx completion fish > ~/.config/fish/completions/sbx.fish
You will need to start a new shell for this setup to take effect.
usage: sbx completion fish [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for fish
- name: no-descriptions
default_value: "false"
usage: disable completion descriptions
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx completion - Generate the autocompletion script for the specified shell

27
data/sbx_cli/sbx_completion_powershell.yaml Normal file
View File

@@ -0,0 +1,27 @@
name: sbx completion powershell
synopsis: Generate the autocompletion script for powershell
description: |
Generate the autocompletion script for powershell.
To load completions in your current shell session:
sbx completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command
to your powershell profile.
usage: sbx completion powershell [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for powershell
- name: no-descriptions
default_value: "false"
usage: disable completion descriptions
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx completion - Generate the autocompletion script for the specified shell

41
data/sbx_cli/sbx_completion_zsh.yaml Normal file
View File

@@ -0,0 +1,41 @@
name: sbx completion zsh
synopsis: Generate the autocompletion script for zsh
description: |
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc
To load completions in your current shell session:
source <(sbx completion zsh)
To load completions for every new session, execute once:
#### Linux:
sbx completion zsh > "${fpath[1]}/_sbx"
#### macOS:
sbx completion zsh > $(brew --prefix)/share/zsh/site-functions/_sbx
You will need to start a new shell for this setup to take effect.
usage: sbx completion zsh [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for zsh
- name: no-descriptions
default_value: "false"
usage: disable completion descriptions
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx completion - Generate the autocompletion script for the specified shell

56
data/sbx_cli/sbx_create.yaml Normal file
View File

@@ -0,0 +1,56 @@
name: sbx create
synopsis: Create a sandbox for an agent
description: |-
Create a sandbox with access to a host workspace for an agent.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create [flags] AGENT PATH [PATH...]
options:
- name: branch
usage: Create a Git worktree on the given branch
- name: help
shorthand: h
default_value: "false"
usage: help for create
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Create a sandbox for Claude in the current directory
sbx create claude .
# Create a sandbox with a custom name
sbx create --name my-project claude /path/to/project
# Create with additional read-only workspaces
sbx create claude . /path/to/docs:ro
# Create with a Git worktree for isolated changes
sbx create --branch=feature/login claude .
see_also:
- sbx - Manage AI coding agent sandboxes.
- sbx create claude - Create a sandbox for claude
- sbx create codex - Create a sandbox for codex
- sbx create copilot - Create a sandbox for copilot
- sbx create docker-agent - Create a sandbox for docker-agent
- sbx create gemini - Create a sandbox for gemini
- sbx create kiro - Create a sandbox for kiro
- sbx create opencode - Create a sandbox for opencode
- sbx create shell - Create a sandbox for shell

49
data/sbx_cli/sbx_create_claude.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create claude
synopsis: Create a sandbox for claude
description: |-
Create a sandbox with access to a host workspace for claude.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create claude PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for claude
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create claude .
# Create with a specific path
sbx create claude /path/to/project
# Create with additional read-only workspaces
sbx create claude . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_codex.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create codex
synopsis: Create a sandbox for codex
description: |-
Create a sandbox with access to a host workspace for codex.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create codex PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for codex
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create codex .
# Create with a specific path
sbx create codex /path/to/project
# Create with additional read-only workspaces
sbx create codex . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_copilot.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create copilot
synopsis: Create a sandbox for copilot
description: |-
Create a sandbox with access to a host workspace for copilot.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create copilot PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for copilot
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create copilot .
# Create with a specific path
sbx create copilot /path/to/project
# Create with additional read-only workspaces
sbx create copilot . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_docker-agent.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create docker-agent
synopsis: Create a sandbox for docker-agent
description: |-
Create a sandbox with access to a host workspace for docker-agent.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create docker-agent PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for docker-agent
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create docker-agent .
# Create with a specific path
sbx create docker-agent /path/to/project
# Create with additional read-only workspaces
sbx create docker-agent . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_gemini.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create gemini
synopsis: Create a sandbox for gemini
description: |-
Create a sandbox with access to a host workspace for gemini.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create gemini PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for gemini
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create gemini .
# Create with a specific path
sbx create gemini /path/to/project
# Create with additional read-only workspaces
sbx create gemini . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_kiro.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create kiro
synopsis: Create a sandbox for kiro
description: |-
Create a sandbox with access to a host workspace for kiro.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create kiro PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for kiro
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create kiro .
# Create with a specific path
sbx create kiro /path/to/project
# Create with additional read-only workspaces
sbx create kiro . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_opencode.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create opencode
synopsis: Create a sandbox for opencode
description: |-
Create a sandbox with access to a host workspace for opencode.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create opencode PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for opencode
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create opencode .
# Create with a specific path
sbx create opencode /path/to/project
# Create with additional read-only workspaces
sbx create opencode . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

49
data/sbx_cli/sbx_create_shell.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx create shell
synopsis: Create a sandbox for shell
description: |-
Create a sandbox with access to a host workspace for shell.
The workspace path is required and will be mounted inside the sandbox at the
same path as on the host. Additional workspaces can be provided as extra
arguments. Append ":ro" to mount them read-only.
Use "sbx run SANDBOX" to attach to the agent after creation.
usage: sbx create shell PATH [PATH...] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for shell
inherited_options:
- name: branch
usage: Create a Git worktree on the given branch
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: |
Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
- name: quiet
shorthand: q
default_value: "false"
usage: Suppress verbose output
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
example: |4-
# Create in the current directory
sbx create shell .
# Create with a specific path
sbx create shell /path/to/project
# Create with additional read-only workspaces
sbx create shell . /path/to/docs:ro
see_also:
- sbx create - Create a sandbox for an agent

58
data/sbx_cli/sbx_exec.yaml Normal file
View File

@@ -0,0 +1,58 @@
name: sbx exec
synopsis: Execute a command inside a sandbox
description: |-
Execute a command in a sandbox. If the sandbox is stopped, it is started first.
Flags match the behavior of "docker exec".
usage: sbx exec [flags] SANDBOX COMMAND [ARG...]
options:
- name: detach
shorthand: d
default_value: "false"
usage: 'Detached mode: run command in the background'
- name: detach-keys
usage: Override the key sequence for detaching a container
- name: env
shorthand: e
default_value: '[]'
usage: Set environment variables
- name: env-file
default_value: '[]'
usage: Read in a file of environment variables
- name: help
shorthand: h
default_value: "false"
usage: help for exec
- name: interactive
shorthand: i
default_value: "false"
usage: Keep STDIN open even if not attached
- name: privileged
default_value: "false"
usage: Give extended privileges to the command
- name: tty
shorthand: t
default_value: "false"
usage: Allocate a pseudo-TTY
- name: user
shorthand: u
usage: 'Username or UID (format: <name|uid>[:<group|gid>])'
- name: workdir
shorthand: w
usage: Working directory inside the container
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Open a shell inside a sandbox
sbx exec -it my-sandbox bash
# Run a command in the background
sbx exec -d my-sandbox npm start
# Run as root
sbx exec -u root my-sandbox apt-get update
see_also:
- sbx - Manage AI coding agent sandboxes.

15
data/sbx_cli/sbx_login.yaml Normal file
View File

@@ -0,0 +1,15 @@
name: sbx login
synopsis: Sign in to Docker
usage: sbx login [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for login
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

15
data/sbx_cli/sbx_logout.yaml Normal file
View File

@@ -0,0 +1,15 @@
name: sbx logout
synopsis: Sign out of Docker
usage: sbx logout [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for logout
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

24
data/sbx_cli/sbx_ls.yaml Normal file
View File

@@ -0,0 +1,24 @@
name: sbx ls
synopsis: List sandboxes
description: |
List all sandboxes with their agent, status, published ports, and workspace.
usage: sbx ls [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for ls
- name: json
default_value: "false"
usage: Output in JSON format
- name: quiet
shorthand: q
default_value: "false"
usage: Only display sandbox names
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

28
data/sbx_cli/sbx_policy.yaml Normal file
View File

@@ -0,0 +1,28 @@
name: sbx policy
synopsis: Manage sandbox policies
description: |-
Manage persistent access policies for sandboxes.
Policies are rules stored locally that control what sandboxes can access.
They apply globally across all sandboxes and persist across restarts.
Use subcommands to allow, deny, list, or remove policies.
usage: sbx policy COMMAND
options:
- name: help
shorthand: h
default_value: "false"
usage: help for policy
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.
- sbx policy allow - Add an allow policy for sandboxes
- sbx policy deny - Add a deny policy for sandboxes
- sbx policy log - Show sandbox policy logs
- sbx policy ls - List sandbox policies
- sbx policy reset - Reset policies to defaults
- sbx policy rm - Remove a policy
- sbx policy set-default - Set the default network policy

21
data/sbx_cli/sbx_policy_allow.yaml Normal file
View File

@@ -0,0 +1,21 @@
name: sbx policy allow
synopsis: Add an allow policy for sandboxes
description: |-
Add a policy that permits sandboxes to access specified resources.
Allowed resources are accessible to all sandboxes. If a resource matches both
an allow and a deny rule, the deny rule takes precedence.
usage: sbx policy allow COMMAND
options:
- name: help
shorthand: h
default_value: "false"
usage: help for allow
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx policy - Manage sandbox policies
- sbx policy allow network - Allow network access to specified hosts

33
data/sbx_cli/sbx_policy_allow_network.yaml Normal file
View File

@@ -0,0 +1,33 @@
name: sbx policy allow network
synopsis: Allow network access to specified hosts
description: |-
Allow sandbox network access to the specified hosts.
RESOURCES is a comma-separated list of hostnames, domains, or IP addresses.
Supports exact domains (example.com), wildcard subdomains (*.example.com),
and optional port suffixes (example.com:443). Use "**" to allow all hosts.
usage: sbx policy allow network RESOURCES [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for network
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Allow access to a single host
sbx policy allow network api.example.com
# Allow access to multiple hosts
sbx policy allow network "api.example.com,cdn.example.com"
# Allow all subdomains of a host
sbx policy allow network "*.npmjs.org"
# Allow all outbound traffic
sbx policy allow network "**"
see_also:
- sbx policy allow - Add an allow policy for sandboxes

21
data/sbx_cli/sbx_policy_deny.yaml Normal file
View File

@@ -0,0 +1,21 @@
name: sbx policy deny
synopsis: Add a deny policy for sandboxes
description: |-
Add a policy that blocks sandboxes from accessing specified resources.
Deny rules always take precedence over allow rules. If a resource matches
both an allow and a deny rule, the request is blocked.
usage: sbx policy deny COMMAND
options:
- name: help
shorthand: h
default_value: "false"
usage: help for deny
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx policy - Manage sandbox policies
- sbx policy deny network - Deny network access to specified hosts

26
data/sbx_cli/sbx_policy_deny_network.yaml Normal file
View File

@@ -0,0 +1,26 @@
name: sbx policy deny network
synopsis: Deny network access to specified hosts
description: |-
Block sandbox network access to the specified hosts.
RESOURCES is a comma-separated list of hostnames, domains, or IP addresses.
Deny rules always take precedence over allow rules.
usage: sbx policy deny network RESOURCES [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for network
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Block access to a host
sbx policy deny network ads.example.com
# Block all outbound traffic
sbx policy deny network "**"
see_also:
- sbx policy deny - Add a deny policy for sandboxes

46
data/sbx_cli/sbx_policy_log.yaml Normal file
View File

@@ -0,0 +1,46 @@
name: sbx policy log
synopsis: Show sandbox policy logs
description: |-
Show policy logs for all sandboxes, or filter by a specific sandbox name.
Displays which hosts were allowed or blocked by the proxy, along with the
matching rule, proxy type, and request count. Useful for debugging connectivity
issues or auditing network activity.
usage: sbx policy log [SANDBOX] [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for log
- name: json
default_value: "false"
usage: Output in JSON format
- name: limit
default_value: "0"
usage: Maximum number of log entries to show
- name: quiet
shorthand: q
default_value: "false"
usage: Only display log entries
- name: type
default_value: all
usage: 'Filter logs by type: "all" or "network" (default "all")'
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Show all policy logs
sbx policy log
# Show logs for a specific sandbox
sbx policy log my-sandbox
# Output in JSON format
sbx policy log --json
# Show the last 20 entries
sbx policy log --limit 20
see_also:
- sbx policy - Manage sandbox policies

29
data/sbx_cli/sbx_policy_ls.yaml Normal file
View File

@@ -0,0 +1,29 @@
name: sbx policy ls
synopsis: List sandbox policies
description: |-
List all active policies.
Displays the policy name (or ID if no name is set), type, decision
(allow/deny), and the associated resources for each rule.
usage: sbx policy ls [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for ls
- name: type
default_value: all
usage: 'Filter policies by type: "all" or "network" (default "all")'
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# List all policies
sbx policy ls
# List only network policies
sbx policy ls --type network
see_also:
- sbx policy - Manage sandbox policies

33
data/sbx_cli/sbx_policy_reset.yaml Normal file
View File

@@ -0,0 +1,33 @@
name: sbx policy reset
synopsis: Reset policies to defaults
description: |-
Remove all custom policies and restart the daemon to restore defaults.
This deletes the local policy store and stops the daemon. When the daemon
restarts (automatically on next command), the default policy is installed.
If sandboxes are currently running, they will be stopped when the daemon
shuts down. You will be prompted for confirmation unless --force is used.
usage: sbx policy reset [flags]
options:
- name: force
shorthand: f
default_value: "false"
usage: Skip confirmation prompt
- name: help
shorthand: h
default_value: "false"
usage: help for reset
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Reset policies (prompts if sandboxes are running)
sbx policy reset
# Reset policies without confirmation
sbx policy reset --force
see_also:
- sbx policy - Manage sandbox policies

17
data/sbx_cli/sbx_policy_rm.yaml Normal file
View File

@@ -0,0 +1,17 @@
name: sbx policy rm
synopsis: Remove a policy
description: Remove a previously added allow or deny policy.
usage: sbx policy rm COMMAND
options:
- name: help
shorthand: h
default_value: "false"
usage: help for rm
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx policy - Manage sandbox policies
- sbx policy rm network - Remove a network policy

32
data/sbx_cli/sbx_policy_rm_network.yaml Normal file
View File

@@ -0,0 +1,32 @@
name: sbx policy rm network
synopsis: Remove a network policy
description: |-
Remove a network policy by rule ID, resource, or both.
Use "sbx policy ls" to see active policies and their IDs/resources.
usage: sbx policy rm network [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for network
- name: id
usage: Remove by rule ID
- name: resource
usage: Remove by resource value(s), comma-separated
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Remove a rule by resource
sbx policy rm network --resource api.example.com
# Remove a rule by ID
sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
# Remove by ID and resource using one filter
sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 --resource "api.example.com,cdn.example.com"
see_also:
- sbx policy rm - Remove a policy

38
data/sbx_cli/sbx_policy_set-default.yaml Normal file
View File

@@ -0,0 +1,38 @@
name: sbx policy set-default
synopsis: Set the default network policy
description: |-
Set the default network policy for all sandboxes.
This must be run before adding custom allow/deny rules or starting a sandbox
for the first time. The default policy determines the baseline network access.
Available policies:
allow-all All outbound network traffic is allowed
balanced Common dev traffic allowed (AI services, package registries, etc.)
deny-all All outbound network traffic is blocked
After setting defaults, use "sbx policy allow/deny" to add custom rules.
Use "sbx policy reset" to clear all policies and start over.
usage: sbx policy set-default <allow-all|balanced|deny-all> [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for set-default
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Set balanced defaults (recommended)
sbx policy set-default balanced
# Allow all traffic
sbx policy set-default allow-all
# Block everything, then allow specific sites
sbx policy set-default deny-all
sbx policy allow network api.example.com:443
see_also:
- sbx policy - Manage sandbox policies

48
data/sbx_cli/sbx_ports.yaml Normal file
View File

@@ -0,0 +1,48 @@
name: sbx ports
synopsis: Manage sandbox port publishing
description: |-
Manage sandbox port publishing.
List, publish, or unpublish ports for a running sandbox. Without --publish or
--unpublish flags, lists all published ports.
Port spec format: [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
If HOST_PORT is omitted, an ephemeral port is allocated automatically.
HOST_IP defaults to 127.0.0.1, PROTOCOL defaults to tcp.
Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6.
usage: sbx ports SANDBOX [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for ports
- name: json
default_value: "false"
usage: Output in JSON format (for port listing)
- name: publish
default_value: '[]'
usage: |
Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
- name: unpublish
default_value: '[]'
usage: |
Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL]
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# List published ports
sbx ports my-sandbox
# Publish sandbox port 8080 to an ephemeral host port
sbx ports my-sandbox --publish 8080
# Publish with a specific host port
sbx ports my-sandbox --publish 3000:8080
# Unpublish a port
sbx ports my-sandbox --unpublish 3000:8080
see_also:
- sbx - Manage AI coding agent sandboxes.

44
data/sbx_cli/sbx_reset.yaml Normal file
View File

@@ -0,0 +1,44 @@
name: sbx reset
synopsis: Reset all sandboxes and clean up state
description: |-
Reset Docker Sandboxes to a freshly-installed state.
This command will:
- Stop all running sandboxes gracefully (30s timeout)
- Clear image cache
- Clear all internal registries
- Delete all sandbox state
- Remove all policies
- Delete all stored secrets
- Sign out of Docker Sandboxes
- Stop the daemon
- Remove all state, cache, and config directories
WARNING: This is destructive and cannot be undone.
Running agents will be terminated and their work lost.
Cached images will be deleted and recreated on next use.
Stored secrets will need to be re-entered.
Use --preserve-secrets to keep stored secrets.
By default, you will be prompted to confirm (y/N).
Use --force to skip the confirmation prompt.
usage: sbx reset [flags]
options:
- name: force
shorthand: f
default_value: "false"
usage: Skip confirmation prompt
- name: help
shorthand: h
default_value: "false"
usage: help for reset
- name: preserve-secrets
default_value: "false"
usage: Keep stored secrets
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

30
data/sbx_cli/sbx_rm.yaml Normal file
View File

@@ -0,0 +1,30 @@
name: sbx rm
synopsis: Remove one or more sandboxes
description: |-
Remove one or more sandboxes and all associated resources.
Stops running sandboxes, removes their containers, cleans up any Git
worktrees, and deletes sandbox state. This action cannot be undone.
Use --all to remove every sandbox (requires confirmation).
Use --force to skip confirmation prompts (for non-interactive scripts).
usage: sbx rm [SANDBOX...] [flags]
options:
- name: all
default_value: "false"
usage: Remove all sandboxes
- name: force
shorthand: f
default_value: "false"
usage: Skip confirmation prompts
- name: help
shorthand: h
default_value: "false"
usage: help for rm
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

49
data/sbx_cli/sbx_run.yaml Normal file
View File

@@ -0,0 +1,49 @@
name: sbx run
synopsis: Run an agent in a sandbox
description: |-
Run an agent in a sandbox, creating the sandbox if it does not already exist.
Pass agent arguments after the "--" separator. Additional workspaces can be
provided as extra arguments. Append ":ro" to mount them read-only.
To create a sandbox without attaching, use "sbx create" instead.
Available agents: claude, codex, copilot, docker-agent, gemini, kiro, opencode, shell
usage: sbx run [flags] SANDBOX | AGENT [PATH...] [-- AGENT_ARGS...]
options:
- name: branch
usage: |
Create a Git worktree on the given branch (use --branch auto to auto-generate)
- name: help
shorthand: h
default_value: "false"
usage: help for run
- name: memory
shorthand: m
usage: |
Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
- name: name
usage: 'Name for the sandbox (default: <agent>-<workdir>)'
- name: template
shorthand: t
usage: |
Container image to use for the sandbox (default: agent-specific image)
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Create and run a sandbox with claude in current directory
sbx run claude
# Create and run with additional workspaces (read-only)
sbx run claude . /path/to/docs:ro
# Run an existing sandbox
sbx run existing-sandbox
# Run a sandbox with agent arguments
sbx run claude -- --continue
see_also:
- sbx - Manage AI coding agent sandboxes.

30
data/sbx_cli/sbx_save.yaml Normal file
View File

@@ -0,0 +1,30 @@
name: sbx save
synopsis: Save a snapshot of the sandbox as a template
description: |-
Save a snapshot of the sandbox as a template.
By default, the image is loaded into the host's Docker daemon (requires Docker to be running).
Use --output to save the image to a tar file instead.
usage: sbx save SANDBOX TAG [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for save
- name: output
shorthand: o
usage: |
Save image to specified tar file instead of loading into host Docker
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Load into host Docker (requires host Docker running)
sbx save my-sandbox myimage:v1.0
# Save to file (works without host Docker)
sbx save my-sandbox myimage:v1.0 --output /tmp/myimage.tar
see_also:
- sbx - Manage AI coding agent sandboxes.

27
data/sbx_cli/sbx_secret.yaml Normal file
View File

@@ -0,0 +1,27 @@
name: sbx secret
synopsis: Manage stored secrets
description: |-
Manage stored secrets for sandbox environments.
Secrets are stored per service name (e.g., "github", "anthropic", "openai").
When a sandbox starts, the proxy uses stored secrets to authenticate API
requests on behalf of the agent. The secret is never exposed directly to the
agent.
Secrets can be scoped globally (shared across all sandboxes) or to a
specific sandbox.
options:
- name: help
shorthand: h
default_value: "false"
usage: help for secret
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.
- sbx secret ls - List stored secrets
- sbx secret rm - Remove a secret
- sbx secret set - Create or update a secret

33
data/sbx_cli/sbx_secret_ls.yaml Normal file
View File

@@ -0,0 +1,33 @@
name: sbx secret ls
synopsis: List stored secrets
usage: sbx secret ls [sandbox] [OPTIONS] [flags]
options:
- name: global
shorthand: g
default_value: "false"
usage: Only list global secrets
- name: help
shorthand: h
default_value: "false"
usage: help for ls
- name: service
usage: Filter by secret service name
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# List all secrets
sbx secret ls
# List only global secrets
sbx secret ls -g
# List secrets for a specific sandbox
sbx secret ls my-sandbox
# Filter by service
sbx secret ls --service github
see_also:
- sbx secret - Manage stored secrets

32
data/sbx_cli/sbx_secret_rm.yaml Normal file
View File

@@ -0,0 +1,32 @@
name: sbx secret rm
synopsis: Remove a secret
usage: sbx secret rm [-g | sandbox] [service] [flags]
options:
- name: force
shorthand: f
default_value: "false"
usage: Delete without confirmation prompt
- name: global
shorthand: g
default_value: "false"
usage: Use global secret scope
- name: help
shorthand: h
default_value: "false"
usage: help for rm
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Remove a global secret
sbx secret rm -g github
# Remove a sandbox-scoped secret
sbx secret rm my-sandbox openai
# Remove without confirmation prompt
sbx secret rm -g github -f
see_also:
- sbx secret - Manage stored secrets

42
data/sbx_cli/sbx_secret_set.yaml Normal file
View File

@@ -0,0 +1,42 @@
name: sbx secret set
synopsis: Create or update a secret
description: |-
Create or update a secret for a service.
Available services: anthropic, aws, github, google, groq, mistral, nebius, openai, xai
When no arguments are provided, an interactive prompt guides you through
scope and service selection.
usage: sbx secret set [-g | sandbox] [service] [flags]
options:
- name: force
shorthand: f
default_value: "false"
usage: Overwrite an existing secret when --token is used
- name: global
shorthand: g
default_value: "false"
usage: Use global secret scope
- name: help
shorthand: h
default_value: "false"
usage: help for set
- name: token
shorthand: t
usage: 'Secret value (less secure: visible in shell history)'
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: |4-
# Store a GitHub token globally (available to all sandboxes)
sbx secret set -g github
# Store an OpenAI key for a specific sandbox
sbx secret set my-sandbox openai
# Non-interactive via stdin (e.g., from a secret manager or env var)
echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic
see_also:
- sbx secret - Manage stored secrets

19
data/sbx_cli/sbx_stop.yaml Normal file
View File

@@ -0,0 +1,19 @@
name: sbx stop
synopsis: Stop one or more sandboxes without removing them
description: |-
Stop one or more running sandboxes without removing them.
Stopped sandboxes retain their state and can be restarted with "sbx run".
usage: sbx stop SANDBOX [SANDBOX...]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for stop
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

15
data/sbx_cli/sbx_version.yaml Normal file
View File

@@ -0,0 +1,15 @@
name: sbx version
synopsis: Show Docker Sandboxes version information
usage: sbx version
options:
- name: help
shorthand: h
default_value: "false"
usage: help for version
inherited_options:
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
see_also:
- sbx - Manage AI coding agent sandboxes.

2
data/summary.yaml
View File

@@ -195,6 +195,8 @@ Docker Pass:
availability: Beta
Docker Projects:
availability: Beta
Docker Sandboxes sbx:
availability: Experimental
Docker Sandboxes:
availability: Experimental
requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later

7
hugo.yaml
View File

@@ -30,6 +30,13 @@ cascade:
- target:
path: /reference/cli/docker/**
layout: cli
# sbx CLI reference pages use the sbx-cli layout (cobra/doc YAML)
- target:
path: /reference/cli/sbx
layout: sbx-cli
- target:
path: /reference/cli/sbx/**
layout: sbx-cli
# Remove the /manuals prefix for content in the manuals section
permalinks:

179
layouts/sbx-cli.html Normal file
View File

@@ -0,0 +1,179 @@
{{ define "article" }}
{{ $data := index site.Data.sbx_cli .Params.datafile }}
{{ .Store.Set "headings" slice }}
<article class="prose min-w-0 max-w-4xl dark:prose-invert">
{{ partial "breadcrumbs.html" . }}
<div class="flex items-start justify-between gap-4">
<h1>{{ .Title }}</h1>
</div>
{{- /* Summary table */ -}}
<div class="overflow-x-auto">
<table>
<tbody>
{{ with $data.synopsis }}
<tr>
<th class="text-left w-32">Description</th>
<td>{{ . }}</td>
</tr>
{{ end }}
{{ with $data.usage }}
<tr>
<th class="text-left w-32">Usage</th>
<td><code>{{ . }}</code></td>
</tr>
{{ end }}
</tbody>
</table>
</div>
{{- /* Description */ -}}
{{ with $data.description }}
{{ $heading := dict "level" 2 "text" "Description" }}
{{ partialCached "heading.html" $heading "sbx-cli-description" }}
{{ $.Store.Add "headings" $heading }}
{{ . | $.RenderString (dict "display" "block") }}
{{ end }}
{{- /* Subcommands (for section pages) */ -}}
{{ if eq .Kind "section" }}
{{ $heading := dict "level" 2 "text" "Commands" }}
{{ partialCached "heading.html" $heading "sbx-cli-commands" }}
{{ $.Store.Add "headings" $heading }}
<table>
<thead>
<tr>
<th class="text-left">Command</th>
<th class="text-left">Description</th>
</tr>
</thead>
<tbody>
{{ range .Pages }}
{{ if .Params.datafile }}
{{ $child := index site.Data.sbx_cli .Params.datafile }}
<tr>
<td class="text-left"><a class="link" href="{{ .Permalink }}"><code>{{ .Title }}</code></a></td>
<td class="text-left">{{ $child.synopsis }}</td>
</tr>
{{ end }}
{{ end }}
</tbody>
</table>
{{ end }}
{{- /* Options */ -}}
{{ with $data.options }}
{{ $opts := where . "name" "ne" "help" }}
{{ with $opts }}
{{ $heading := dict "level" 2 "text" "Options" }}
{{ partialCached "heading.html" $heading "sbx-cli-options" }}
{{ $.Store.Add "headings" $heading }}
<div class="overflow-x-auto">
<table>
<thead class="bg-gray-100 dark:bg-gray-800">
<tr>
<th class="p-2">Option</th>
<th class="p-2">Default</th>
<th class="p-2">Description</th>
</tr>
</thead>
<tbody>
{{ range . }}
<tr>
<td>
<code>{{ with .shorthand }}-{{ . }}, {{ end }}--{{ .name }}</code>
</td>
{{ $skipDefault := `[],false,` }}
<td>
{{ with .default_value }}
{{ cond (in $skipDefault .) "" (printf "<code>%s</code>" . | safeHTML) }}
{{ end }}
</td>
<td>
{{ with .usage }}
{{ strings.TrimSpace . }}
{{ end }}
</td>
</tr>
{{ end }}
</tbody>
</table>
</div>
{{ end }}
{{ end }}
{{- /* Inherited (global) options */ -}}
{{ with $data.inherited_options }}
{{ $opts := where . "name" "ne" "help" }}
{{ with $opts }}
{{ $heading := dict "level" 2 "text" "Global options" }}
{{ partialCached "heading.html" $heading "sbx-cli-global-options" }}
{{ $.Store.Add "headings" $heading }}
<div class="overflow-x-auto">
<table>
<thead class="bg-gray-100 dark:bg-gray-800">
<tr>
<th class="p-2">Option</th>
<th class="p-2">Default</th>
<th class="p-2">Description</th>
</tr>
</thead>
<tbody>
{{ range . }}
<tr>
<td>
<code>{{ with .shorthand }}-{{ . }}, {{ end }}--{{ .name }}</code>
</td>
{{ $skipDefault := `[],false,` }}
<td>
{{ with .default_value }}
{{ cond (in $skipDefault .) "" (printf "<code>%s</code>" . | safeHTML) }}
{{ end }}
</td>
<td>
{{ with .usage }}
{{ strings.TrimSpace . }}
{{ end }}
</td>
</tr>
{{ end }}
</tbody>
</table>
</div>
{{ end }}
{{ end }}
{{- /* Examples */ -}}
{{ with $data.example }}
{{ $heading := dict "level" 2 "text" "Examples" }}
{{ partialCached "heading.html" $heading "sbx-cli-examples" }}
{{ $.Store.Add "headings" $heading }}
{{- /* Dedent: strip up to 6 leading spaces from each line */ -}}
{{ $dedented := replaceRE `(?m)^ {2,6}` "" . }}
{{ $code := printf "```console\n%s\n```" (strings.TrimSpace $dedented) }}
{{ $code | $.RenderString (dict "display" "block") }}
{{ end }}
</article>
{{ end }}
{{ define "right" }}
<div class="hidden min-w-52 flex-1 lg:block">
<aside class="sticky top-16 h-[calc(100vh-64px)] min-w-52 space-y-4 overflow-y-auto py-4 w-full">
<div id="TableOfContents">
<div class="text-lg pb-2">{{ T "tableOfContents" }}</div>
<nav class="toc">
<ul>
{{ range (.Store.Get "headings") }}
{{ $text := .text }}
<li{{ with .level }} class="pl-{{ . }}"{{ end }}>
<a href="#{{ $text | anchorize }}">{{ markdownify $text }}</a>
</li>
{{ end }}
</ul>
</nav>
</div>
</aside>
</div>
{{ end }}