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

sandboxes: add agent-specific documentation

Browse Source 
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
2026-02-13 15:12:04 +01:00
parent cc292c16cb
commit 87fa1fa09b
15 changed files with 815 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -97,6 +97,7 @@ Google
Grafana
Gravatar
gRPC
Groq
Grype
HyperKit
inferencing
@@ -115,6 +116,7 @@ JFrog
JUnit
Kata
Kerberos
Kiro
Kitematic
Kubeadm
kubectl
@@ -196,6 +198,7 @@ stargz
stdin
stdout
subfolder
sudo
subvolume
Syft
syntaxes

27
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
@@ -49,9 +49,10 @@ $ 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
@@ -85,14 +86,16 @@ that workspace.
Docker Sandboxes works with multiple AI coding agents:
- **Claude Code** - Anthropic's coding agent
- **OpenCode** - Multi-provider agent with AGENTS.md support
- **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
- **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)
For detailed configuration instructions, see [Supported agents](agents/).
## Get started

31
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
---
@@ -20,7 +21,7 @@ inside microVMs with private Docker daemons.
| cagent | `cagent` | Experimental | In development |
| Kiro | `kiro` | Experimental | In development |
| OpenCode | `opencode` | Experimental | In development |
| Shell | `shell` | Experimental | Minimal environment for manual setup |
| Custom shell | `shell` | Experimental | Minimal environment for manual setup |
## Experimental status
@@ -44,6 +45,19 @@ $ 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
Each agent has its own credential requirements and authentication flow.
@@ -52,7 +66,14 @@ 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.

39
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:
@@ -42,8 +47,7 @@ This starts Claude and immediately processes the prompt.
## Authentication
Claude Code requires an Anthropic API key. Credentials are scoped per sandbox
and must be provided through environment variables or interactive login.
Claude Code requires an Anthropic API key. Credentials are scoped per sandbox.
### Environment variable (recommended)
@@ -85,7 +89,7 @@ When using interactive authentication:
- 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
@@ -104,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.

13
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
@@ -24,7 +26,7 @@ Before you begin, ensure you have:
## 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.
@@ -148,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)

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

@@ -194,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.

2
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 -->

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

@@ -15,22 +15,23 @@ Create a sandbox for your project:
```console
$ cd ~/my-project
$ docker sandbox run claude
$ docker sandbox run AGENT
```
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 claude ~/my-project
$ 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 claude ~/my-project # Creates sandbox
$ docker sandbox run claude ~/my-project # Reuses same sandbox
$ 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
@@ -45,8 +46,8 @@ When using the `--name` flag, the behavior is also idempotent based on the
name:
```console
$ docker sandbox run --name dev claude # Creates sandbox named "dev"
$ docker sandbox run --name dev claude # Reuses sandbox "dev"
$ docker sandbox run --name dev AGENT # Creates sandbox named "dev"
$ docker sandbox run --name dev AGENT # Reuses sandbox "dev"
```
## Installing dependencies
@@ -55,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.
@@ -77,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
```
@@ -90,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
@@ -148,8 +149,8 @@ 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
$ docker sandbox create codex ~/project-b
$ docker sandbox create copilot ~/work/client-project
```
Each sandbox is completely isolated. Switch between them by running the
@@ -168,14 +169,14 @@ directory (for example, `claude-my-project`). You can also specify custom names
using the `--name` flag:
```console
$ docker sandbox run --name myproject claude ~/project
$ 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
```
@@ -188,7 +189,7 @@ 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 claude ~/my-project ~/shared-docs
$ docker sandbox run AGENT ~/my-project ~/shared-docs
```
The primary workspace (first argument) is always mounted read-write. Additional
@@ -199,7 +200,7 @@ workspaces are mounted read-write by default.
Mount additional workspaces as read-only by appending `:ro` or `:readonly`:
```console
$ docker sandbox run claude . /path/to/docs:ro /path/to/lib:readonly
$ docker sandbox run AGENT . /path/to/docs:ro /path/to/lib:readonly
```
The primary workspace remains fully writable while read-only workspaces are
@@ -214,7 +215,7 @@ Example:
```console
$ cd /Users/bob/projects
$ docker sandbox run claude ./app ~/docs:ro
$ docker sandbox run AGENT ./app ~/docs:ro
```
Inside the sandbox: