centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 14:28:47 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #24102 from dvdksn/sandboxes-461

Browse Source 
sandboxes v0.12.0
This commit is contained in:
David Karlsson
2026-02-18 11:05:53 +01:00
committed by GitHub
parent 95e834fe44 6b7d2fd0ff
commit e32f9cc592
34 changed files with 1326 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -13,8 +13,8 @@ params:
{{< summary-bar feature_name="Docker Sandboxes" >}}
Docker Sandboxes lets you run AI coding agents in isolated environments on your
machine. If you're building with agents like Claude Code, Sandboxes provides a
secure way to give agents autonomy without compromising your system.
machine. Sandboxes provides a secure way to give agents autonomy without
compromising your system.
## Why use Docker Sandboxes
@@ -45,12 +45,14 @@ coding agents, see [Comparison to alternatives](./architecture.md#comparison-to-
To create and run a sandbox:
```console
$ docker sandbox run claude ~/my-project
$ cd ~/my-project
$ docker sandbox run claude
```
This command creates a sandbox for your workspace (`~/my-project`) and starts
the Claude Code agent inside it. The agent can now work with your code, install
tools, and run containers inside the isolated sandbox.
Replace `claude` with your [preferred agent](./agents/_index.md). This command
creates a sandbox for your workspace (`~/my-project`) and starts the agent. The
agent can now work with your code, install tools, and run containers inside the
isolated sandbox.
## How it works
@@ -84,12 +86,16 @@ that workspace.
Docker Sandboxes works with multiple AI coding agents:
- **Claude Code** - Anthropic's coding agent
- **Codex** - OpenAI's Codex agent (partial support; in development)
- **Copilot** - GitHub Copilot agent (partial support; in development)
- **Gemini** - Google's Gemini agent (partial support; in development)
- **cagent** - Docker's [cagent](/ai/cagent/) (partial support; in development)
- **Kiro** - by AWS (partial support; in development)
- **Claude Code** - Anthropic's coding agent (production-ready)
- **Codex** - OpenAI's Codex agent (in development)
- **Copilot** - GitHub Copilot agent (in development)
- **Gemini** - Google's Gemini agent (in development)
- **OpenCode** - Multi-provider agent with TUI interface (in development)
- **cagent** - Docker's multi-provider coding agent (in development)
- **Kiro** - Interactive agent with device flow auth (in development)
- **Shell** - Minimal sandbox for manual agent installation
For detailed configuration instructions, see [Supported agents](agents/).
## Get started

59
content/manuals/ai/sandboxes/agents.md → content/manuals/ai/sandboxes/agents/_index.md
View File

@@ -1,5 +1,6 @@
---
title: Supported agents
linkTitle: Agents
description: AI coding agents supported by Docker Sandboxes with experimental status and configuration details.
weight: 50
---
@@ -11,14 +12,16 @@ inside microVMs with private Docker daemons.
## Supported agents
| Agent | Command | Status | Notes |
| ----------- | ---------- | ------------ | -------------------------- |
| Claude Code | `claude` | Experimental | Most tested implementation |
| Codex | `codex` | Experimental | In development |
| Copilot | `copilot` | Experimental | In development |
| Gemini | `gemini` | Experimental | In development |
| cagent | `cagent` | Experimental | In development |
| Kiro | `kiro` | Experimental | In development |
| Agent | Command | Status | Notes |
| ----------- | ---------- | ------------ | ----------------------------------------- |
| Claude Code | `claude` | Experimental | Most tested implementation |
| Codex | `codex` | Experimental | In development |
| Copilot | `copilot` | Experimental | In development |
| Gemini | `gemini` | Experimental | In development |
| cagent | `cagent` | Experimental | In development |
| Kiro | `kiro` | Experimental | In development |
| OpenCode | `opencode` | Experimental | In development |
| Custom shell | `shell` | Experimental | Minimal environment for manual setup |
## Experimental status
@@ -36,23 +39,41 @@ Use sandboxes for development and testing, not production workloads.
The agent type is specified when creating a sandbox:
```console
$ docker sandbox create claude ~/my-project
$ docker sandbox create codex ~/my-project
$ docker sandbox create copilot ~/my-project
$ docker sandbox create gemini ~/my-project
$ docker sandbox create cagent ~/my-project
$ docker sandbox create kiro ~/my-project
$ docker sandbox create AGENT [PATH] [PATH...]
```
Each agent runs in its own isolated sandbox. The agent type is bound to the
sandbox when created and cannot be changed later.
## Template environment
All agent templates share a common base environment:
- Ubuntu 25.10 base
- Development tools: Docker CLI (with Buildx and Compose), Git, GitHub CLI, Node.js, Go, Python 3, uv, make, jq, ripgrep
- Non-root `agent` user with sudo access
- Private Docker daemon for running additional containers
- Package managers: apt, pip, npm
Individual agents add their specific CLI tools on top of this base. See
[Custom templates](../templates.md) to build your own agent images.
## Agent-specific configuration
Different agents may require different authentication methods or configuration.
Each agent has its own credential requirements and authentication flow.
Credentials are scoped per agent and must be provided specifically for that
agent (no fallback authentication methods are used).
See the agent-specific documentation:
- [Claude Code configuration](claude-code.md)
- [Claude Code](./claude-code.md)
- [cagent](./cagent.md)
- [Codex](./codex.md)
- [Copilot](./copilot.md)
- [Gemini](./gemini.md)
- [Kiro](./kiro.md)
- [OpenCode](./opencode.md)
- [Custom shell](./shell.md)
## Requirements
@@ -61,9 +82,3 @@ See the agent-specific documentation:
- macOS with virtualization.framework
- Windows with Hyper-V {{< badge color=violet text=Experimental >}}
- API keys or credentials for your chosen agent
## Next steps
- [Claude Code configuration](claude-code.md)
- [Custom templates](templates.md)
- [Using sandboxes effectively](workflows.md)

96
content/manuals/ai/sandboxes/agents/cagent.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: cagent sandbox
description: |
Use Docker cagent in Docker Sandboxes with multi-provider authentication
supporting OpenAI, Anthropic, and more.
keywords: docker, sandboxes, cagent, ai agent, multi-provider, authentication
weight: 60
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide covers authentication, configuration, and usage of Docker cagent in
a sandboxed environment. [cagent](/ai/cagent/) is Docker's open source coding
agent that supports multiple providers.
## Quick start
Create a sandbox and run cagent for a project directory:
```console
$ docker sandbox run cagent ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run cagent
```
## Authentication
cagent uses proxy-managed authentication for all supported providers. Docker
Sandboxes intercepts API requests and injects credentials transparently. You
provide your API keys through environment variables, and the sandbox handles
credential management.
### Supported providers
Configure one or more providers by setting environment variables:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export OPENAI_API_KEY=sk-xxxxx
export ANTHROPIC_API_KEY=sk-ant-xxxxx
export GOOGLE_API_KEY=AIzaSyxxxxx
export XAI_API_KEY=xai-xxxxx
export NEBIUS_API_KEY=xxxxx
export MISTRAL_API_KEY=xxxxx
```
You only need to configure the providers you want to use. cagent detects
available credentials and routes requests to the appropriate provider.
### Environment variable setup
Docker Sandboxes use a daemon process that doesn't inherit environment
variables from your current shell session. To make your API keys available to
sandboxes, set them globally in your shell configuration file.
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the new environment variables
3. Create and run your sandbox:
```console
$ docker sandbox create cagent ~/project
$ docker sandbox run <sandbox-name>
```
The sandbox detects the environment variables and uses them automatically.
## Configuration
cagent supports YOLO mode that disables safety checks and approval prompts.
This mode grants the agent full access to your sandbox environment without
interactive confirmation.
### Pass options at runtime
Pass cagent CLI options after the sandbox name and a `--` separator:
```console
$ docker sandbox run <sandbox-name> -- run --yolo
```
The `run --yolo` command starts cagent with approval prompts disabled.
## Base image
Template: `docker/sandbox-templates:cagent`
cagent supports multiple LLM providers with automatic credential injection
through the sandbox proxy. Launches with `run --yolo` by default.
See [Custom templates](../templates.md) to build your own agent images.

52
content/manuals/ai/sandboxes/claude-code.md → content/manuals/ai/sandboxes/agents/claude-code.md
View File

@@ -1,7 +1,10 @@
---
title: Configure Claude Code
description: Learn how to configure Claude Code authentication, pass CLI options, and customize your sandboxed agent environment with Docker.
weight: 30
title: Claude Code sandbox
description: |
Use Claude Code in Docker Sandboxes with authentication, configuration, and
YOLO mode for AI-assisted development.
keywords: docker, sandboxes, claude code, anthropic, ai agent, authentication, configuration
weight: 10
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
@@ -9,6 +12,8 @@ weight: 30
This guide covers authentication, configuration files, and common options for
running Claude Code in a sandboxed environment.
Official documentation: [Claude Code](https://code.claude.com/docs)
## Quick start
To create a sandbox and run Claude Code for a project directory:
@@ -17,6 +22,13 @@ To create a sandbox and run Claude Code for a project directory:
$ docker sandbox run claude ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run claude
```
### Pass a prompt directly
Start Claude with a specific prompt:
@@ -35,7 +47,7 @@ This starts Claude and immediately processes the prompt.
## Authentication
Claude Code requires an Anthropic API key. You can authenticate using an environment variable (recommended) or through interactive login.
Claude Code requires an Anthropic API key. Credentials are scoped per sandbox.
### Environment variable (recommended)
@@ -66,15 +78,18 @@ The sandbox detects the environment variable and uses it automatically.
### Interactive authentication
If no credentials are found, Claude Code prompts you to authenticate interactively when it starts. You can also trigger the login flow manually using the `/login` command within Claude Code.
If the `ANTHROPIC_API_KEY` environment variable is not set, Claude Code prompts
you to authenticate interactively when it starts. You can also trigger the login
flow manually using the `/login` command within Claude Code.
When using interactive authentication:
- You'll need to authenticate for each workspace/sandbox separately
- You must authenticate each sandbox separately
- If the sandbox is removed or destroyed, you'll need to authenticate again when you recreate it
- Authentication sessions aren't persisted outside the sandbox
- No fallback authentication methods are used
To avoid repeated authentication, use the `ANTHROPIC_API_KEY` environment variable method described above.
To avoid repeated authentication, set the `ANTHROPIC_API_KEY` environment variable.
## Configuration
@@ -93,28 +108,13 @@ For example:
$ docker sandbox run <sandbox-name> -- --continue
```
See the [Claude Code CLI reference](https://docs.claude.com/en/docs/claude-code/cli-reference)
See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
for available options.
## Base image
The Claude Code sandbox template is a container image that runs inside the
sandbox VM. It includes:
Template: `docker/sandbox-templates:claude-code`
- Ubuntu-based environment with Claude Code
- Development tools: Docker CLI, GitHub CLI, Node.js, Go, Python 3, Git, ripgrep, jq
- Non-root `agent` user with sudo access
- Private Docker daemon for running additional containers
Claude Code launches with `--dangerously-skip-permissions` by default in sandboxes.
Claude launches with `--dangerously-skip-permissions` by default in sandboxes.
You can build custom templates based on `docker/sandbox-templates:claude-code`.
See [Custom templates](templates.md) for details.
## Next steps
- [Using sandboxes effectively](workflows.md)
- [Custom templates](templates.md)
- [Network policies](network-policies.md)
- [Troubleshooting](troubleshooting.md)
- [CLI Reference](/reference/cli/docker/sandbox/)
See [Custom templates](../templates.md) to build your own agent images.

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

@@ -0,0 +1,93 @@
---
title: Codex sandbox
description: |
Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO
mode configuration.
keywords: docker, sandboxes, codex, openai, ai agent, authentication, yolo mode
weight: 20
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
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
$ docker sandbox run codex ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run codex
```
## Authentication
Codex requires an OpenAI API key. Credentials are scoped per sandbox.
Set the `OPENAI_API_KEY` environment variable in your shell configuration file.
Docker Sandboxes use a daemon process that doesn't inherit environment
variables from your current shell session. To make your API key available to
sandboxes, set it globally in your shell configuration file.
Add the API key to your shell configuration file:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export OPENAI_API_KEY=sk-xxxxx
```
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the new environment variable
3. Create and run your sandbox:
```console
$ docker sandbox create codex ~/project
$ docker sandbox run <sandbox-name>
```
The sandbox detects the environment variable and uses it automatically.
## Configuration
Codex supports a YOLO mode that disables safety checks and approval prompts.
This mode grants the agent full access to your sandbox environment without
interactive confirmation.
Configure YOLO mode in `~/.codex/config.toml`:
```toml
approval_policy = "never"
sandbox_mode = "danger-full-access"
```
With these settings, Codex runs without approval prompts.
### Pass options at runtime
Pass Codex CLI options after the sandbox name and a `--` separator:
```console
$ docker sandbox run <sandbox-name> -- --dangerously-bypass-approvals-and-sandbox
```
This flag enables YOLO mode for a single session without modifying the
configuration file.
## Base image
Template: `docker/sandbox-templates:codex`
Codex launches with `--dangerously-bypass-approvals-and-sandbox` by default when YOLO mode is configured.
See [Custom templates](../templates.md) to build your own agent images.

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

@@ -0,0 +1,102 @@
---
title: Copilot sandbox
description: |
Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and
trusted folder configuration.
keywords: docker, sandboxes, copilot, github, ai agent, authentication, trusted folders
weight: 30
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
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
$ docker sandbox run copilot ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run copilot
```
## Authentication
Copilot requires a GitHub token with Copilot access. Credentials are scoped
per sandbox and must be provided through environment variables on the host.
### Environment variable (recommended)
Set the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in your shell
configuration file.
Docker Sandboxes use a daemon process that doesn't inherit environment
variables from your current shell session. To make your token available to
sandboxes, set it globally in your shell configuration file.
Add the token to your shell configuration file:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export GH_TOKEN=ghp_xxxxx
```
Or use `GITHUB_TOKEN`:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export GITHUB_TOKEN=ghp_xxxxx
```
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the new environment variable
3. Create and run your sandbox:
```console
$ docker sandbox create copilot ~/project
$ docker sandbox run <sandbox-name>
```
The sandbox detects the environment variable and uses it automatically.
## Configuration
Copilot can be configured to trust specific folders, disabling safety prompts
for those locations. Configure trusted folders in `~/.copilot/config.json`:
```json
{
"trusted_folders": ["/workspace", "/home/agent/projects"]
}
```
Workspaces are mounted at `/workspace` by default, so trusting this path
allows Copilot to operate without repeated confirmations.
### Pass options at runtime
Pass Copilot CLI options after the sandbox name and a `--` separator:
```console
$ docker sandbox run <sandbox-name> -- --yolo
```
The `--yolo` flag disables approval prompts for a single session without
modifying the configuration file.
## Base image
Template: `docker/sandbox-templates:copilot`
Copilot launches with `--yolo` by default when trusted folders are configured.
See [Custom templates](../templates.md) to build your own agent images.

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

@@ -0,0 +1,118 @@
---
title: Gemini sandbox
description: |
Use Google Gemini in Docker Sandboxes with proxy-managed authentication and
API key configuration.
keywords: docker, sandboxes, gemini, google, ai agent, authentication, proxy
weight: 40
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
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
$ docker sandbox run gemini ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run gemini
```
## Authentication
Gemini uses proxy-managed authentication. Docker Sandboxes intercepts API
requests and injects credentials transparently. You provide your API key
through environment variables on the host, and the sandbox handles credential
management.
### Environment variable (recommended)
Set the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable in your
shell configuration file.
Docker Sandboxes use a daemon process that doesn't inherit environment
variables from your current shell session. To make your API key available to
sandboxes, set it globally in your shell configuration file.
Add the API key to your shell configuration file:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export GEMINI_API_KEY=AIzaSyxxxxx
```
Or use `GOOGLE_API_KEY`:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export GOOGLE_API_KEY=AIzaSyxxxxx
```
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the new environment variable
3. Create and run your sandbox:
```console
$ docker sandbox create gemini ~/project
$ docker sandbox run <sandbox-name>
```
The sandbox detects the environment variable and uses it automatically.
### Interactive authentication
If neither `GEMINI_API_KEY` nor `GOOGLE_API_KEY` is set, Gemini prompts you to
sign in when it starts.
When using interactive authentication:
- You must authenticate each sandbox separately
- If the sandbox is removed or destroyed, you'll need to authenticate again when you recreate it
- Authentication sessions aren't persisted outside the sandbox
- No fallback authentication methods are used
To avoid repeated authentication, set the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable.
## Configuration
Configure Gemini behavior in `~/.gemini/settings.json`:
```json
{
"disable_sandbox_tool": true,
"trusted_folders": ["/workspace"]
}
```
These settings disable safety checks and allow Gemini to operate without
repeated confirmations for workspace files.
### Pass options at runtime
Pass Gemini CLI options after the sandbox name and a `--` separator:
```console
$ docker sandbox run <sandbox-name> -- --yolo
```
The `--yolo` flag disables approval prompts for a single session without
modifying the configuration file.
## Base image
Template: `docker/sandbox-templates:gemini`
Gemini is configured to disable its built-in OAuth flow. Authentication is managed through the Docker Sandbox proxy with API keys.
See [Custom templates](../templates.md) to build your own agent images.

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

@@ -0,0 +1,94 @@
---
title: Kiro sandbox
description: |
Use Kiro in Docker Sandboxes with device flow authentication for interactive
AI-assisted development.
keywords: docker, sandboxes, kiro, ai agent, authentication, device flow
weight: 70
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
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
$ docker sandbox run kiro ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox 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
$ docker sandbox run <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
Kiro requires minimal configuration. The agent runs with trust-all-tools mode
by default, which allows it to execute commands without repeated approval
prompts.
### Pass options at runtime
Pass Kiro CLI options after the sandbox name and a `--` separator:
```console
$ docker sandbox run <sandbox-name> -- chat --trust-all-tools
```
The `chat --trust-all-tools` command starts Kiro with approval prompts
disabled.
## Base image
Template: `docker/sandbox-templates:kiro`
Kiro manages authentication through an interactive device flow. The authentication database is persisted across sandbox restarts. Launches with `chat --trust-all-tools` by default.
See [Custom templates](../templates.md) to build your own agent images.

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

@@ -0,0 +1,103 @@
---
title: OpenCode sandbox
description: |
Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI
interface for AI development.
keywords: docker, sandboxes, opencode, ai agent, multi-provider, authentication, tui
weight: 50
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
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
$ docker sandbox run opencode ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run opencode
```
OpenCode launches a TUI (text user interface) where you can select your
preferred LLM provider and interact with the agent.
## Authentication
OpenCode uses proxy-managed authentication for all supported providers. Docker
Sandboxes intercepts API requests and injects credentials transparently. You
provide your API keys through environment variables on the host, and the
sandbox handles credential management.
### Supported providers
Configure one or more providers by setting environment variables:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export OPENAI_API_KEY=sk-xxxxx
export ANTHROPIC_API_KEY=sk-ant-xxxxx
export GOOGLE_API_KEY=AIzaSyxxxxx
export XAI_API_KEY=xai-xxxxx
export GROQ_API_KEY=gsk_xxxxx
export AWS_ACCESS_KEY_ID=AKIA_xxxxx
export AWS_SECRET_ACCESS_KEY=xxxxx
export AWS_REGION=us-west-2
```
You only need to configure the providers you want to use. OpenCode detects
available credentials and offers those providers in the TUI.
### Environment variable setup
Docker Sandboxes use a daemon process that doesn't inherit environment
variables from your current shell session. To make your API keys available to
sandboxes, set them globally in your shell configuration file.
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the new environment variables
3. Create and run your sandbox:
```console
$ docker sandbox create opencode ~/project
$ docker sandbox run <sandbox-name>
```
The sandbox detects the environment variables and uses them automatically.
## Configuration
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 templates](../templates.md) to build your own agent images.

126
content/manuals/ai/sandboxes/agents/shell.md Normal file
View File

@@ -0,0 +1,126 @@
---
title: Custom shell
description: |
Use the custom shell sandbox for manual agent installation and custom
development environments in Docker Sandboxes.
keywords: docker, sandboxes, shell, custom, manual setup, development environment
weight: 80
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide covers the Shell sandbox, a minimal environment for custom agent
installation and development. Unlike other agent sandboxes, Shell doesn't
include a pre-installed agent binary. Instead, it provides a clean environment
where you can install and configure any agent or tool.
## Quick start
Create a sandbox and launch a shell environment:
```console
$ docker sandbox run shell ~/my-project
```
The workspace parameter is optional and defaults to the current directory:
```console
$ cd ~/my-project
$ docker sandbox run shell
```
This launches a bash login shell inside the sandbox.
## Use cases
The Shell sandbox serves several purposes:
- Custom agent installation
Install agents not officially supported by Docker Sandboxes. The environment
includes package managers and development tools for installing arbitrary
software.
- Agent development
Test custom agent implementations or modifications in an isolated environment
with a private Docker daemon.
- Manual configuration
Configure agents with complex setup requirements or custom authentication
flows that aren't supported by the standard templates.
- Troubleshooting
Debug agent issues by manually running commands and inspecting the sandbox
environment.
## Authentication
The Shell sandbox uses proxy credential injection. The proxy automatically
injects credentials into API requests for supported providers (OpenAI,
Anthropic, Google, GitHub, etc.).
Set your API keys in your shell configuration file:
```plaintext {title="~/.bashrc or ~/.zshrc"}
export OPENAI_API_KEY=sk-xxxxx
export ANTHROPIC_API_KEY=sk-ant-xxxxx
export GOOGLE_API_KEY=AIzaSyxxxxx
export GH_TOKEN=ghp_xxxxx
```
Apply the changes:
1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
2. Restart Docker Desktop so the daemon picks up the environment variables
3. Create and run your sandbox:
```console
$ docker sandbox create shell ~/project
$ docker sandbox run <sandbox-name>
```
The proxy reads credentials from your host environment and injects them into
API requests automatically. Credentials are never stored inside the sandbox.
## Installing agents
Once inside the shell sandbox, install agents using their standard installation
methods.
### Example: Installing Continue
[Continue](https://continue.dev) is an AI code assistant. Since Node.js is
pre-installed, you can install it directly:
```console
$ npm install -g @continuedev/cli
$ cn --version
1.5.43
```
For containerized agents or complex setups, consider creating a [custom
template](../templates.md) based on the shell template instead of installing
interactively.
## Running commands
Pass shell options after the `--` separator to execute commands:
```console
$ docker sandbox run <sandbox-name> -- -c "echo 'Hello from sandbox'"
```
## Base image
Template: `docker/sandbox-templates:shell`
The shell template provides the base environment without a pre-installed agent,
making it suitable for manual agent installation.
See [Custom templates](../templates.md) to build your own agent images.
The minimal nature of this template makes it suitable as a base for any custom
agent installation.

29
content/manuals/ai/sandboxes/architecture.md
View File

@@ -153,6 +153,29 @@ An HTTP/HTTPS filtering proxy runs on your host and is available at
web requests. You can configure network policies to control which destinations
are allowed. See [Network policies](network-policies.md).
### Credential injection
The HTTP/HTTPS proxy automatically injects credentials into API requests for
supported providers (OpenAI, Anthropic, Google, GitHub, etc.). When you set
environment variables like `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` on your
host, the proxy intercepts outbound requests to those services and adds the
appropriate authentication headers.
This approach keeps credentials on your host system - they're never stored
inside the sandbox VM. The agent makes API requests without credentials, and
the proxy injects them transparently. When the sandbox is removed, no
credentials remain inside.
For multi-provider agents (OpenCode, cagent), the proxy automatically selects
the correct credentials based on the API endpoint being called. See individual
[agent configuration](agents/) for credential setup instructions.
When building custom templates or installing agents manually in the shell
sandbox, some agents may 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 will inject actual credentials
regardless of the environment variable value.
### Sandbox isolation
Sandboxes cannot communicate with each other. Each VM has its own private
@@ -200,9 +223,3 @@ Sandboxes trade higher resource overhead (VM + 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.
## Next steps
- [Network policies](network-policies.md)
- [Custom templates](templates.md)
- [Using sandboxes effectively](workflows.md)

40
content/manuals/ai/sandboxes/get-started.md
View File

@@ -1,13 +1,15 @@
---
title: Get started with Docker Sandboxes
linkTitle: Get started
description: Run Claude Code in an isolated sandbox. Quick setup guide with prerequisites and essential commands.
description: Run AI coding agents in isolated sandboxes. Quick setup guide using Claude Code as an example.
weight: 20
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide shows how to run Claude Code in an isolated sandbox for the first time.
This guide shows how to run an AI coding agent in an isolated sandbox for the
first time, using Claude Code as an example. The same concepts apply to
[other supported agents](agents/).
> [!NOTE]
> Upgrading from an earlier version of Docker Desktop? See the
@@ -19,12 +21,12 @@ This guide shows how to run Claude Code in an isolated sandbox for the first tim
Before you begin, ensure you have:
- Docker Desktop 4.58 or later
- macOS, or Windows {{< badge color=violet text=Experimental >}}
- macOS or Windows {{< badge color=violet text=Experimental >}}
- A Claude API key (can be provided via environment variable or interactively)
## Run your first sandbox
Follow these steps to run Claude Code:
Follow these steps to run a sandbox with Claude Code:
1. (Optional but recommended) Set your Anthropic API key as an environment variable.
@@ -51,10 +53,26 @@ Follow these steps to run Claude Code:
2. Create and run a sandbox for Claude Code for your workspace:
```console
$ docker sandbox run claude ~/my-project
$ docker sandbox run claude [PATH]
```
This creates a microVM sandbox. Docker assigns it a name automatically.
This creates a microVM sandbox. Docker assigns it a name automatically based
on the agent and workspace directory (`claude-somedir`). If that name is
already in use, Docker appends a number.
The workspace parameter is optional and defaults to your current directory
if omitted:
```console
$ cd ~/my-project
$ docker sandbox run claude
```
You can also mount multiple workspaces. Append `:ro` for read-only access:
```console
$ docker sandbox run claude ~/my-project ~/docs:ro
```
3. Claude Code starts and you can begin working. The first run takes longer
while Docker initializes the microVM and pulls the template image.
@@ -86,7 +104,8 @@ Here are essential commands to manage your sandboxes:
$ docker sandbox ls
```
Shows all your sandboxes with their IDs, names, status, and creation time.
Shows all your sandboxes with their IDs, names, status, workspace paths, and
creation time. Workspace paths are shown for both running and stopped sandboxes.
> [!NOTE]
> Sandboxes don't appear in `docker ps` because they're microVMs, not
@@ -120,7 +139,7 @@ To start fresh with a clean environment, remove and recreate the sandbox:
```console
$ docker sandbox rm <sandbox-name>
$ docker sandbox run claude ~/project
$ docker sandbox run claude [PATH]
```
Configuration like custom templates and workspace paths are set when you create
@@ -131,10 +150,9 @@ For a complete list of commands and options, see the
## Next steps
Now that you have Claude running in a sandbox, learn more about:
Now that you have an agent running in a sandbox, learn more about:
- [Claude Code configuration](claude-code.md)
- [Supported agents](agents.md)
- [Supported agents](agents/_index.md)
- [Using sandboxes effectively](workflows.md)
- [Custom templates](templates.md)
- [Network policies](network-policies.md)

19
content/manuals/ai/sandboxes/migration.md
View File

@@ -6,9 +6,9 @@ weight: 100
{{< summary-bar feature_name="Docker Sandboxes" >}}
Docker Desktop 4.58 introduces microVM-based sandboxes, replacing the previous
container-based implementation. This guide helps you migrate from legacy
sandboxes to the new architecture.
The most recent versions of Docker Desktop create microVM-based sandboxes,
replacing the container-based implementation released in earlier versions. This
guide helps you migrate from legacy sandboxes to the new architecture.
## What changed
@@ -20,7 +20,7 @@ policies.
> If you need to use legacy container-based sandboxes, install
> [Docker Desktop 4.57](/desktop/release-notes/#4570).
After upgrading to Docker Desktop 4.58:
After upgrading to Docker Desktop 4.58 or later:
- Old sandboxes don't appear in `docker sandbox ls`
- They still exist as regular Docker containers and volumes
@@ -121,10 +121,15 @@ template.
```console
$ docker sandbox create --template my-sandbox-template:v1 \
--load-local-template \
--pull-template=never \
claude ~/project
```
> [!NOTE]
> The `--pull-template` flag was introduced in Docker Desktop 4.61 (Sandbox
> version 0.12). For Docker Desktop 4.58–4.60, substitute
> `--pull-template=never` with `--load-local-template`.
5. Run the sandbox:
```console
@@ -189,5 +194,5 @@ New command structure:
$ docker sandbox run claude ~/project
```
The agent name (`claude`, `codex`, `gemini`, `cagent`, `kiro`) is now a
required parameter when creating sandboxes, and you run the sandbox by name.
The agent name is now a required parameter when creating sandboxes, and you run
the sandbox by name.

85
content/manuals/ai/sandboxes/network-policies.md
View File

@@ -61,6 +61,32 @@ the allow-list (e.g., `localhost:1234`).
HTTP requests to `host.docker.internal` are rewritten to `localhost`, so only
the name `localhost` will work in the allow-list.
## Default policy
New sandboxes use this default policy unless you configure a custom policy:
**Policy mode:** `allow` (permit all traffic except what's explicitly blocked)
**Blocked CIDRs:**
- `10.0.0.0/8` - Private network (Class A)
- `127.0.0.0/8` - Loopback addresses
- `169.254.0.0/16` - Link-local addresses
- `172.16.0.0/12` - Private network (Class B)
- `192.168.0.0/16` - Private network (Class C)
- `::1/128` - IPv6 loopback
- `fc00::/7` - IPv6 unique local addresses
- `fe80::/10` - IPv6 link-local addresses
**Allowed hosts:**
- `*.anthropic.com` - Claude API and services
- `platform.claude.com:443` - Claude platform services
The default policy blocks access to private networks, localhost, and cloud
metadata services while allowing internet access. Explicitly allowed hosts
bypass CIDR checks for performance.
## Monitor network activity
View what your agent is accessing and whether requests are being blocked:
@@ -69,7 +95,43 @@ View what your agent is accessing and whether requests are being blocked:
$ docker sandbox network log
```
Network logs help you understand agent behavior and define policies.
The network log shows aggregated summaries of HTTP/HTTPS network requests:
- **Allowed requests** - Requests that were permitted by your network policy
- **Blocked requests** - Requests that were denied by your network policy
For each host accessed, the log shows:
- **Sandbox** - Name of the sandbox making the request
- **Host** - The destination (hostname and port)
- **Rule** - The policy rule that matched this request (or `<default policy>`)
- **Last Seen** - When this host was most recently accessed
- **Count** - Number of requests to this host since tracking began
Use network logs to understand agent behavior, identify blocked requests that
should be allowed, and debug network policy issues. The logs are especially
helpful when defining policies - they show exactly what your agent is trying to
access.
### Example log output
```console
$ docker sandbox network log
Blocked requests:
SANDBOX HOST RULE LAST SEEN COUNT
my-sandbox internal.corp.com:443 <default policy> 14:30:15 12-Feb 3
my-sandbox 192.168.1.100:22 <default policy> 14:25:10 12-Feb 1
Allowed requests:
SANDBOX HOST RULE LAST SEEN COUNT
my-sandbox api.anthropic.com:443 api.anthropic.com 14:35:21 12-Feb 15
my-sandbox registry.npmjs.org:443 *.npmjs.org 14:32:18 12-Feb 8
my-sandbox raw.githubusercontent.com:443 *.githubusercontent.com 14:30:45 12-Feb 2
```
The log displays both blocked and allowed requests in separate sections. Use
`--json` for machine-readable output, `--quiet` to suppress headers, or
`--limit N` to show only the first N entries.
## Applying policies
@@ -100,16 +162,8 @@ This policy:
> [!NOTE]
> These CIDR blocks are already blocked by default. The example above shows how
> to explicitly configure them if needed. The default policy blocks:
>
> - `10.0.0.0/8`
> - `127.0.0.0/8`
> - `169.254.0.0/16`
> - `172.16.0.0/12`
> - `192.168.0.0/16`
> - `::1/128`
> - `fc00::/7`
> - `fe80::/10`
> to explicitly configure them. See [Default policy](#default-policy) for the
> complete list.
### Example: Restrict to package managers only
@@ -317,8 +371,7 @@ first sandbox starts, but only if it doesn't already exist.
The current default policy is `allow`, which permits all outbound connections
except to blocked CIDR ranges (private networks, localhost, and cloud metadata
services). This default will change to `deny` in a future release to provide
more restrictive defaults.
services).
You can modify the default policy:
@@ -332,9 +385,3 @@ You can modify the default policy:
Review and customize the default policy to match your security requirements
before creating new sandboxes. Once created, the default policy file won't be
modified by upgrades, preserving your custom configuration.
## Next steps
- [Architecture](architecture.md)
- [Using sandboxes effectively](workflows.md)
- [Custom templates](templates.md)

56
content/manuals/ai/sandboxes/templates.md
View File

@@ -68,21 +68,47 @@ $ docker build -t my-template:v1 .
Use it directly from your local Docker daemon:
```console
$ docker sandbox run --load-local-template -t my-template:v1 claude ~/project
$ docker sandbox run --pull-template never -t my-template:v1 claude [PATH]
```
The `--load-local-template` flag tells the sandbox to use an image from your
local Docker daemon. Without it, the sandbox looks for the image in a registry.
The `--pull-template never` flag tells the sandbox to use local template
images.
To share the template with others, push it to a registry:
```console
$ docker tag my-template:v1 myorg/my-template:v1
$ docker push myorg/my-template:v1
$ docker sandbox run -t myorg/my-template:v1 claude ~/project
$ docker sandbox run -t myorg/my-template:v1 claude [PATH]
```
Once pushed to a registry, you don't need `--load-local-template`.
For registry images, the default `--pull-template missing` policy automatically
pulls if not cached.
## Template caching and pull policies
Docker Sandboxes caches template images to speed up sandbox creation. The
`--pull-template` flag controls when images are pulled from registries.
- `--pull-template missing` (default)
Pull the image only if it's not already cached locally. First sandbox
creation automatically pulls the image, and subsequent sandboxes are created
quickly because the image is cached.
- `--pull-template always`
Always pull the image from the registry before creating the sandbox, even if
it's cached. Slower than `missing` but guarantees freshness.
- `--pull-template never`
Use only cached images. Never pull from a registry. Fails if the image isn't
in the cache.
The cache stores template images separately from your host Docker daemon's
images. Cached images persist across sandbox creation and deletion, but are
removed when you run `docker sandbox reset`.
## Creating templates from existing sandboxes
@@ -100,21 +126,21 @@ Inside the sandbox, ask the agent to install tools and configure the
environment. Once everything works, exit and save the sandbox as a template:
```console
$ docker sandbox save claude-sandbox-2026-02-02-123456 my-template:v1
$ docker sandbox save claude-project my-template:v1
✓ Saved sandbox as my-template:v1
```
This saves the image to your local Docker daemon. Use `--load-local-template`
This saves the image to your local Docker daemon. Use `--pull-template never`
to create new sandboxes from it:
```console
$ docker sandbox run --load-local-template -t my-template:v1 claude ~/other-project
$ docker sandbox run --pull-template never -t my-template:v1 claude ~/other-project
```
To save as a tar file instead (for example, to transfer to another machine):
```console
$ docker sandbox save -o template.tar claude-sandbox-2026-02-02-123456 my-template:v1
$ docker sandbox save -o template.tar claude-project my-template:v1
```
Use a Dockerfile when you want a clear record of how the environment is built.
@@ -157,8 +183,8 @@ base, but they don't include agent binaries or sandbox configuration.
Using a standard image directly creates the sandbox but fails at runtime:
```console
$ docker sandbox create --template python:3-slim claude ~/project
✓ Created sandbox claude-sandbox-2026-01-16-170525 in VM claude-project
$ docker sandbox create --template python:3-slim claude [PATH]
✓ Created sandbox claude-project
$ docker sandbox run claude-project
agent binary "claude" not found in sandbox: verify this is the correct sandbox type
@@ -187,14 +213,8 @@ $ docker push myorg/my-template:v1.0
Team members use the template by referencing the registry image:
```console
$ docker sandbox run -t myorg/sandbox-templates:python-v1.0 claude ~/project
$ docker sandbox run -t myorg/sandbox-templates:python-v1.0 claude [PATH]
```
Use version tags like `:v1.0` instead of `:latest` for consistency across your
team.
## Next steps
- [Using sandboxes effectively](workflows.md)
- [Architecture](architecture.md)
- [Network policies](network-policies.md)

16
content/manuals/ai/sandboxes/troubleshooting.md
View File

@@ -6,7 +6,7 @@ weight: 50
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide helps you resolve common issues when sandboxing Claude Code locally.
This guide helps you resolve common issues when using Docker Sandboxes with AI coding agents.
<!-- vale off -->
@@ -119,3 +119,17 @@ If this happens, recover by closing the OpenVMM processes:
To avoid this issue, launch sandboxes one at a time rather than creating
multiple sandboxes concurrently.
## Persistent issues or corrupted state
If sandboxes behave unexpectedly or fail to start, reset all sandbox state:
```console
$ docker sandbox reset
```
This stops all running VMs and deletes all sandbox data. The daemon continues
running. After reset, create fresh sandboxes as needed.
Use reset when troubleshooting persistent problems or to reclaim disk space from
all sandboxes at once.

176
content/manuals/ai/sandboxes/workflows.md
View File

@@ -15,14 +15,39 @@ Create a sandbox for your project:
```console
$ cd ~/my-project
$ docker sandbox run claude .
$ docker sandbox run AGENT
```
The sandbox persists. Stop and restart it without losing installed packages or
Replace `AGENT` with your preferred agent (`claude`, `codex`, `copilot`, etc.).
The workspace defaults to your current directory when omitted. You can also
specify an explicit path:
```console
$ docker sandbox run AGENT ~/my-project
```
The `docker sandbox run` command is idempotent. Running the same command
multiple times reuses the existing sandbox instead of creating a new one:
```console
$ docker sandbox run AGENT ~/my-project # Creates sandbox
$ docker sandbox run AGENT ~/my-project # Reuses same sandbox
```
This works with workspace path (absolute or relative) or omitted workspace. The
sandbox persists. Stop and restart it without losing installed packages or
configuration:
```console
$ docker sandbox run <sandbox-name> # Reconnect later
$ docker sandbox run <sandbox-name> # Reconnect by name
```
When using the `--name` flag, the behavior is also idempotent based on the
name:
```console
$ docker sandbox run --name dev AGENT # Creates sandbox named "dev"
$ docker sandbox run --name dev AGENT # Reuses sandbox "dev"
```
## Installing dependencies
@@ -31,10 +56,10 @@ Ask the agent to install what's needed:
```plaintext
You: "Install pytest and black"
Claude: [Installs packages via pip]
Agent: [Installs packages via pip]
You: "Install build-essential"
Claude: [Installs via apt]
Agent: [Installs via apt]
```
The agent has sudo access. Installed packages persist for the sandbox lifetime.
@@ -53,7 +78,7 @@ runs inside the sandbox's private Docker daemon.
```plaintext
You: "Build the Docker image and run the tests"
Claude: *runs*
Agent: *runs*
docker build -t myapp:test .
docker run myapp:test npm test
```
@@ -66,7 +91,7 @@ don't appear in your host's `docker ps`.
```plaintext
You: "Start the application with docker-compose and run integration tests"
Claude: *runs*
Agent: *runs*
docker-compose up -d
docker-compose exec api pytest tests/integration
docker-compose down
@@ -92,6 +117,9 @@ To preserve a configured environment, create a [Custom template](templates.md).
## Security considerations
Agents running in sandboxes automatically trust the workspace directory without
prompting. This enables agents to work freely within the isolated environment.
Agents can create and modify any files in your mounted workspace, including
scripts, configuration files, and hidden files.
@@ -115,25 +143,126 @@ Check for untracked files and be aware that some changes, like Git hooks in
This is the same trust model used by editors like Visual Studio Code, which
warn when opening new workspaces for similar reasons.
## Named sandboxes
## Managing multiple projects
Use meaningful names for sandboxes you'll reuse:
Create sandboxes for different projects:
```console
$ docker sandbox run --name myproject claude ~/project
$ docker sandbox create claude ~/project-a
$ docker sandbox create codex ~/project-b
$ docker sandbox create copilot ~/work/client-project
```
Each sandbox is completely isolated. Switch between them by running the
appropriate sandbox name.
Remove unused sandboxes to reclaim disk space:
```console
$ docker sandbox rm <sandbox-name>
```
## Named sandboxes
Docker automatically generates sandbox names based on the agent and workspace
directory (for example, `claude-my-project`). You can also specify custom names
using the `--name` flag:
```console
$ docker sandbox run --name myproject AGENT ~/project
```
Create multiple sandboxes for the same workspace:
```console
$ docker sandbox create --name dev claude ~/project
$ docker sandbox create --name staging claude ~/project
$ docker sandbox create --name staging codex ~/project
$ docker sandbox run dev
```
Each maintains separate packages, Docker images, and state, but share the
workspace files.
## Multiple workspaces
Mount multiple directories into a single sandbox for working with related
projects or when the agent needs access to documentation and shared libraries.
```console
$ docker sandbox run AGENT ~/my-project ~/shared-docs
```
The primary workspace (first argument) is always mounted read-write. Additional
workspaces are mounted read-write by default.
### Read-only mounts
Mount additional workspaces as read-only by appending `:ro` or `:readonly`:
```console
$ docker sandbox run AGENT . /path/to/docs:ro /path/to/lib:readonly
```
The primary workspace remains fully writable while read-only workspaces are
protected from changes.
### Path resolution
Workspaces are mounted at their absolute paths inside the sandbox. Relative
paths are resolved to absolute paths before mounting.
Example:
```console
$ cd /Users/bob/projects
$ docker sandbox run AGENT ./app ~/docs:ro
```
Inside the sandbox:
- `/Users/bob/projects/app` - Primary workspace (read-write)
- `/Users/bob/docs` - Additional workspace (read-only)
Changes to `/Users/bob/projects/app` sync back to your host, while
`/Users/bob/docs` remains read-only.
### Sharing workspaces across sandboxes
A single path can be included in multiple sandboxes simultaneously:
```console
$ docker sandbox create --name sb1 claude ./project-a
$ docker sandbox create --name sb2 claude ./project-a ./project-b
$ docker sandbox create --name sb3 cagent ./project-a
$ docker sandbox ls
SANDBOX AGENT STATUS WORKSPACE
sb1 claude running /Users/bob/src/project-a
sb2 claude running /Users/bob/src/project-a, /Users/bob/src/project-b
sb3 cagent running /Users/bob/src/project-a
```
Each sandbox runs in isolation with separate configurations while sharing the
same workspace files.
## Resetting state
If you encounter issues with sandbox state, use the reset command to clean up
all VMs and registries:
```console
$ docker sandbox reset
```
This command:
- Stops all running sandbox VMs
- Deletes all VM state and registries
- Continues running the sandbox daemon (does not shut it down)
- Warns about directories it cannot remove
After reset, you can create fresh sandboxes. Use this when troubleshooting
persistent issues or reclaiming disk space from all sandboxes at once.
## Debugging
Access the sandbox directly with an interactive shell:
@@ -155,28 +284,3 @@ List all sandboxes:
```console
$ docker sandbox ls
```
## Managing multiple projects
Create sandboxes for different projects:
```console
$ docker sandbox create claude ~/project-a
$ docker sandbox create claude ~/project-b
$ docker sandbox create claude ~/work/client-project
```
Each sandbox is completely isolated. Switch between them by running the
appropriate sandbox name.
Remove unused sandboxes to reclaim disk space:
```console
$ docker sandbox rm <sandbox-name>
```
## Next steps
- [Custom templates](templates.md)
- [Architecture](architecture.md)
- [Network policies](network-policies.md)

6
content/reference/cli/docker/sandbox/create/opencode.md Normal file
View File

@@ -0,0 +1,6 @@
---
datafolder: sandbox-cli
datafile: docker_sandbox_create_opencode
title: docker sandbox create opencode
layout: cli
---

6
content/reference/cli/docker/sandbox/create/shell.md Normal file
View File

@@ -0,0 +1,6 @@
---
datafolder: sandbox-cli
datafile: docker_sandbox_create_shell
title: docker sandbox create shell
layout: cli
---