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

ai: add docs for local agent sandboxes

Browse Source 
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
2025-11-05 14:01:09 +01:00
parent 546686293c
commit fabb108e1f
14 changed files with 861 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,7 @@
(?i)[A-Z]{2,}'?s
jq
ripgrep
sandboxing
Adreno
Aleksandrov
Amazon

4
content/manuals/ai/compose/_index.md
View File

@@ -2,8 +2,8 @@
build:
render: never
title: AI and Docker Compose
weight: 40
weight: 50
params:
sidebar:
group: AI
---
---

2
content/manuals/ai/gordon/_index.md
View File

@@ -1,7 +1,7 @@
---
title: Ask Gordon
description: Streamline your workflow with Docker's AI-powered assistant in Docker Desktop and CLI.
weight: 10
weight: 40
params:
sidebar:
badge:

2
content/manuals/ai/mcp-catalog-and-toolkit/_index.md
View File

@@ -7,7 +7,7 @@ params:
badge:
color: blue
text: Beta
weight: 30
weight: 10
description: Learn about Docker's MCP catalog on Docker Hub
keywords: Docker, ai, mcp servers, ai agents, extension, docker desktop, llm, docker hub
grid:

141
content/manuals/ai/mcp-catalog-and-toolkit/sandboxes.md → content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md
View File

@@ -1,37 +1,18 @@
---
title: Sandboxes
description: "Learn how sandboxes provide secure, isolated execution environments for AI agents in the MCP ecosystem, enabling safe code execution and protecting production systems."
keywords: Sandboxes, E2B, MCP Gateway, isolated environment, AI agent security
params:
sidebar:
badge:
color: green
text: New
weight: 50
title: E2B sandboxes
description: Cloud-based secure sandboxes for AI agents with built-in Docker MCP Gateway integration
keywords: E2B, cloud sandboxes, MCP Gateway, AI agents, MCP Catalog
aliases:
- /ai/mcp-catalog-and-toolkit/sandboxes/
---
Sandboxes are isolated execution environments that provide secure, controlled spaces for running code and applications without affecting the host system. They create strict boundaries around executing processes, preventing access to unauthorized resources while providing consistent, reproducible environments. Think of it as a virtual "playground" with clearly defined boundaries, where code can execute freely within those boundaries but cannot escape to impact other systems or access sensitive data.
Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. Through this partnership, every E2B sandbox includes direct access to Docker's [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools from publishers including GitHub, Notion, and Stripe.
In the Model Context Protocol ecosystem, sandboxes address several critical challenges that arise when AI agents need to execute code or interact with external systems. They enable safe code execution for AI-generated scripts, secure tool validation for MCP servers, and multi-tenant isolation when multiple agents share infrastructure. This ensures that sensitive credentials and data remain protected within appropriate security boundaries while maintaining compliance and audit requirements.
## Key features
- Isolation and Security: Complete separation between executing code and the host environment, with strict controls over file access, network connections, and system calls.
- Resource Management: Fine-grained control over CPU, memory, disk space, and network usage to prevent resource exhaustion.
- Reproducible Environments: Consistent, predictable execution environments. Code that runs successfully in one sandbox instance will behave identically in another.
- Ephemeral Environments: Temporary, disposable environments that can be destroyed after task completion, leaving no persistent artifacts.
## E2B sandboxes
Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. Through this partnership, every E2B sandbox now includes direct access to Docker’s [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools, including ones from known publishers such as GitHub, Notion, and Stripe, all enabled through the Docker MCP Gateway.
When creating a new sandbox, E2B users can specify which MCP tools the sandbox should access. E2B then launches these MCP tools and provides access through the Docker MCP Gateway.
The following example shows how to set up an E2B sandbox with GitHub and Notion MCP servers.
When you create a sandbox, you specify which MCP tools it should access. E2B launches these tools and provides access through the Docker MCP Gateway.
## Example: Using GitHub and Notion MCP server
The following example demonstrates how to analyze data in Notion and create GitHub issues. By the end, you'll understand how to connect multiple MCP servers in an E2B sandbox and orchestrate cross-platform workflows.
This example demonstrates how to connect multiple MCP servers in an E2B sandbox. You'll analyze data in Notion and create GitHub issues using Claude.
### Prerequisites
@@ -40,29 +21,28 @@ Before you begin, make sure you have the following:
- [E2B account](https://e2b.dev/docs/quickstart) with API access
- Anthropic API key for Claude
>[!Note]
>
> This example uses Claude CLI which comes pre-installed in E2B sandboxes. However,
> you can adapt the example to work with other AI assistants of your choice. See
> [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) for alternative
> connection methods.
> [!NOTE]
> This example uses Claude Code which comes pre-installed in E2B sandboxes.
> However, you can adapt the example to work with other AI assistants of your
> choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart)
> for alternative connection methods.
- Node.js 18+ installed on your machine
- Notion account with:
- A database containing sample data
- [Integration token](https://www.notion.com/help/add-and-manage-connections-with-the-api)
- GitHub account with:
- A repository for testing
- Personal access token with `repo` scope
- A repository for testing
- Personal access token with `repo` scope
### Set up your environment
Create a new directory and initialize a Node.js project:
```bash
mkdir mcp-e2b-quickstart
cd mcp-e2b-quickstart
npm init -y
```console
$ mkdir mcp-e2b-quickstart
$ cd mcp-e2b-quickstart
$ npm init -y
```
Configure your project for ES modules by updating `package.json`:
@@ -80,24 +60,26 @@ Configure your project for ES modules by updating `package.json`:
Install required dependencies:
```bash
npm install e2b dotenv
```console
$ npm install e2b dotenv
```
Create a `.env` file with your credentials:
```bash
```console
$ cat > .env << 'EOF'
E2B_API_KEY=your_e2b_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
NOTION_INTEGRATION_TOKEN=ntn_your_notion_integration_token_here
GITHUB_TOKEN=ghp_your_github_pat_here
EOF
```
Protect your credentials:
```bash
echo ".env" >> .gitignore
echo "node_modules/" >> .gitignore
```console
$ echo ".env" >> .gitignore
$ echo "node_modules/" >> .gitignore
```
### Create an E2B sandbox with MCP servers
@@ -108,8 +90,8 @@ echo "node_modules/" >> .gitignore
Create a file named `index.ts`:
```typescript
import 'dotenv/config';
import { Sandbox } from 'e2b';
import "dotenv/config";
import { Sandbox } from "e2b";
async function quickstart(): Promise<void> {
console.log("Creating E2B sandbox with Notion and GitHub MCP servers...\n");
@@ -120,7 +102,8 @@ async function quickstart(): Promise<void> {
},
mcp: {
notion: {
internalIntegrationToken: process.env.NOTION_INTEGRATION_TOKEN as string,
internalIntegrationToken: process.env
.NOTION_INTEGRATION_TOKEN as string,
},
githubOfficial: {
githubPersonalAccessToken: process.env.GITHUB_TOKEN as string,
@@ -135,17 +118,17 @@ async function quickstart(): Promise<void> {
console.log(`MCP Gateway URL: ${mcpUrl}\n`);
// Wait for MCP initialization
await new Promise<void>(resolve => setTimeout(resolve, 1000));
await new Promise<void>((resolve) => setTimeout(resolve, 1000));
// Connect Claude CLI to MCP gateway
console.log("Connecting Claude CLI to MCP gateway...");
// Connect Claude to MCP gateway
console.log("Connecting Claude to MCP gateway...");
await sbx.commands.run(
`claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
{
timeoutMs: 0,
onStdout: console.log,
onStderr: console.log
}
onStderr: console.log,
},
);
console.log("\nConnection successful! Cleaning up...");
@@ -157,8 +140,8 @@ quickstart().catch(console.error);
Run the script:
```typescript
npx tsx index.ts
```console
$ npx tsx index.ts
```
{{< /tab >}}
@@ -200,8 +183,8 @@ async def quickstart():
# Wait for MCP initialization
await asyncio.sleep(1)
# Connect Claude CLI to MCP gateway
print("Connecting Claude CLI to MCP gateway...")
# Connect Claude to MCP gateway
print("Connecting Claude to MCP gateway...")
def on_stdout(output):
print(output, end='')
@@ -229,8 +212,8 @@ if __name__ == "__main__":
Run the script:
```python
python index.py
```console
$ python index.py
```
{{< /tab >}}
@@ -238,13 +221,13 @@ python index.py
You should see:
```bash
```console
Creating E2B sandbox with Notion and GitHub MCP servers...
Sandbox created successfully!
MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp
Connecting Claude CLI to MCP gateway...
Connecting Claude to MCP gateway...
Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp
Connection successful! Cleaning up...
@@ -257,7 +240,7 @@ Now, test the setup by running a simple workflow that searches Notion and create
{{< tabs group="" >}}
{{< tab name="Typescript">}}
>[!IMPORTANT]
> [!IMPORTANT]
>
> Replace `owner/repo` in the prompt with your actual GitHub username and repository
> name (for example, `yourname/test-repo`).
@@ -265,8 +248,8 @@ Now, test the setup by running a simple workflow that searches Notion and create
Update `index.ts` with the following example:
```typescript
import 'dotenv/config';
import { Sandbox } from 'e2b';
import "dotenv/config";
import { Sandbox } from "e2b";
async function exampleWorkflow(): Promise<void> {
console.log("Creating sandbox...\n");
@@ -277,7 +260,8 @@ async function exampleWorkflow(): Promise<void> {
},
mcp: {
notion: {
internalIntegrationToken: process.env.NOTION_INTEGRATION_TOKEN as string,
internalIntegrationToken: process.env
.NOTION_INTEGRATION_TOKEN as string,
},
githubOfficial: {
githubPersonalAccessToken: process.env.GITHUB_TOKEN as string,
@@ -291,7 +275,7 @@ async function exampleWorkflow(): Promise<void> {
console.log("Sandbox created successfully\n");
// Wait for MCP servers to initialize
await new Promise<void>(resolve => setTimeout(resolve, 3000));
await new Promise<void>((resolve) => setTimeout(resolve, 3000));
console.log("Connecting Claude to MCP gateway...\n");
await sbx.commands.run(
@@ -299,8 +283,8 @@ async function exampleWorkflow(): Promise<void> {
{
timeoutMs: 0,
onStdout: console.log,
onStderr: console.log
}
onStderr: console.log,
},
);
console.log("\nRunning example: Search Notion and create GitHub issue...\n");
@@ -315,8 +299,8 @@ async function exampleWorkflow(): Promise<void> {
{
timeoutMs: 0,
onStdout: console.log,
onStderr: console.log
}
onStderr: console.log,
},
);
await sbx.kill();
@@ -327,8 +311,8 @@ exampleWorkflow().catch(console.error);
Run the script:
```typescript
npx tsx index.ts
```console
$ npx tsx index.ts
```
{{< /tab >}}
@@ -336,7 +320,7 @@ npx tsx index.ts
Update `index.py` with this example:
>[!IMPORTANT]
> [!IMPORTANT]
>
> Replace `owner/repo` in the prompt with your actual GitHub username and repository
> name (for example, `yourname/test-repo`).
@@ -418,8 +402,8 @@ if __name__ == "__main__":
Run the script:
```bash
python workflow.py
```console
$ python workflow.py
```
{{< /tab >}}
@@ -427,7 +411,7 @@ python workflow.py
You should see:
```bash
```console
Creating sandbox...
Running example: Search Notion and create GitHub issue...
@@ -456,14 +440,13 @@ Successfully created test issue:
Both operations completed successfully. The MCP servers are properly configured and working.
```
You've successfully created an E2B sandbox with multiple MCP servers and used Claude to orchestrate a workflow across Notion and GitHub.
You can extend this example to combine any of the 200+ MCP servers in the Docker MCP Catalog to build sophisticated automation workflows for your specific needs.
The sandbox connected multiple MCP servers and orchestrated a workflow across Notion and GitHub. You can extend this pattern to combine any of the 200+ MCP servers in the Docker MCP Catalog.
## Related pages
- [How to build an AI-powered code quality workflow with SonarQube and E2B](/guides/github-sonarqube-sandbox.md)
- [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/)
- [Docker Sandboxes](/manuals/ai/sandboxes/_index.md)
- [Docker MCP Toolkit and Catalog](/manuals/ai/mcp-catalog-and-toolkit/_index.md)
- [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
- [E2B MCP documentation](https://e2b.dev/docs/mcp)

2
content/manuals/ai/model-runner/_index.md
View File

@@ -4,7 +4,7 @@ linkTitle: Model Runner
params:
sidebar:
group: AI
weight: 20
weight: 30
description: Learn how to use Docker Model Runner to manage and run AI models.
keywords: Docker, ai, model runner, docker desktop, docker engine, llm
aliases:

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

@@ -0,0 +1,70 @@
---
title: Docker Sandboxes
description: Run AI agents in isolated environments
weight: 20
params:
sidebar:
group: AI
badge:
color: violet
text: Experimental
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
Docker Sandboxes simplifies running AI agents securely on your local machine.
Designed for developers building with coding agents like Claude Code, Sandboxes
isolate your agents from your local machine while preserving a familiar
development experience. With Docker Sandboxes, agents can execute commands,
install packages, and modify files inside a containerized workspace that
mirrors your local directory. This gives you full agent autonomy without
compromising safety.
## How it works
When you run `docker sandbox run <agent>`:
1. Docker creates a container from a template image and mounts your current
working directory into the container at the same path.
2. Docker discovers your Git `user.name` and `user.email` configuration and
injects it into the container so commits made by the agent are attributed
to you.
3. On first run, you're prompted to authenticate. Credentials are stored in a
Docker volume and reused for future sandboxed agents.
4. The agent starts inside the container with bypass permissions enabled.
### Workspace mounting
Your workspace directory is mounted into the container at the same absolute path
(on macOS and Linux). For example, `/Users/alice/projects/myapp` on your host
is also `/Users/alice/projects/myapp` in the container. This means:
- File paths in error messages match your host
- Scripts with hard-coded paths work as expected
- Changes to workspace files are immediately visible on both host and container
### One sandbox per workspace
Docker enforces one sandbox per workspace. When you run `docker sandbox run
<agent>` in the same directory, Docker reuses the existing container. This
means state (installed packages, temporary files) persists across agent sessions
in that workspace.
> [!NOTE]
> To change a sandbox's configuration (environment variables, mounted volumes,
> etc.), you need to remove and recreate it. See
> [Managing sandboxes](advanced-config.md#managing-sandboxes) for details.
## Release status
Docker Sandboxes is an experimental feature. Features and setup are subject to
change.
Report issues on [GitHub](https://github.com/docker/desktop-feedback).
## Get started
Head to the [Get started guide](get-started.md) to run your first sandboxed agent.

305
content/manuals/ai/sandboxes/advanced-config.md Normal file
View File

@@ -0,0 +1,305 @@
---
title: Advanced configurations
linkTitle: Advanced
description: Docker access, volume mounting, environment variables, custom templates, and sandbox management.
weight: 40
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide covers advanced configurations for sandboxed agents running locally.
## Managing sandboxes
### Recreating sandboxes
Since Docker enforces one sandbox per workspace, the same sandbox is reused
each time you run `docker sandbox run <agent>` in a given directory. To create
a fresh sandbox, you need to remove the existing one first:
```console
$ docker sandbox ls # Find the sandbox ID
$ docker sandbox rm <sandbox-id>
$ docker sandbox run <agent> # Creates a new sandbox
```
### When to recreate sandboxes
Sandboxes remember their initial configuration and don't pick up changes from subsequent `docker sandbox run` commands. You must recreate the sandbox to modify:
- Environment variables (the `-e` flag)
- Volume mounts (the `-v` flag)
- Docker socket access (the `--mount-docker-socket` flag)
- Credentials mode (the `--credentials` flag)
### Listing and inspecting sandboxes
View all your sandboxes:
```console
$ docker sandbox ls
```
Get detailed information about a specific sandbox:
```console
$ docker sandbox inspect <sandbox-id>
```
This shows the sandbox's configuration, including environment variables, volumes, and creation time.
### Removing sandboxes
Remove a specific sandbox:
```console
$ docker sandbox rm <sandbox-id>
```
Remove all sandboxes at once:
```console
$ docker sandbox rm $(docker sandbox ls -q)
```
This is useful for cleanup when you're done with a project or want to start fresh.
## Giving agents access to Docker
Mount the Docker socket to give agents access to Docker commands inside the
container. The agent can build images, run containers, and work with Docker
Compose setups.
> [!CAUTION]
> Mounting the Docker socket grants the agent full access to your Docker daemon,
> which has root-level privileges on your system. The agent can start or stop
> any container, access volumes, and potentially escape the sandbox. Only use
> this option when you fully trust the code the agent is working with.
### Enable Docker socket access
Use the `--mount-docker-socket` flag:
```console
$ docker sandbox run --mount-docker-socket claude
```
This mounts your host's Docker socket (`/var/run/docker.sock`) into the
container, giving the agent access to Docker commands.
> [!IMPORTANT]
> The agent can see and interact with all containers on your host, not just
> those created within the sandbox.
### Example: Testing a containerized application
If your project has a Dockerfile, the agent can build and test it:
```console
$ cd ~/my-docker-app
$ docker sandbox run --mount-docker-socket claude
```
Example conversation:
```plaintext
You: "Build the Docker image and run the tests"
Claude: *runs*
docker build -t myapp:test .
docker run myapp:test npm test
```
### What agents can do with Docker socket access
With Docker access enabled, agents can:
- Start multi-container applications with Docker Compose
- Build images for multiple architectures
- Manage existing containers on your host
- Validate Dockerfiles and test build processes
## Environment variables
Pass environment variables to configure the sandbox environment with the `-e`
flag:
```console
$ docker sandbox run \
-e NODE_ENV=development \
-e DATABASE_URL=postgresql://localhost/myapp_dev \
-e DEBUG=true \
claude
```
These variables are available to all processes in the container, including the
agent and any commands it runs. Use multiple `-e` flags for multiple variables.
### Example: Development environment setup
Set up a complete development environment:
```console
$ docker sandbox run \
-e NODE_ENV=development \
-e DATABASE_URL=postgresql://localhost/myapp_dev \
-e REDIS_URL=redis://localhost:6379 \
-e LOG_LEVEL=debug \
claude
```
Example conversation:
```plaintext
You: "Run the database migrations and start the development server"
Claude: *uses DATABASE_URL and other environment variables*
npm run migrate
npm run dev
```
### Common use cases
API keys for testing:
```console
$ docker sandbox run \
-e STRIPE_TEST_KEY=sk_test_xxx \
-e SENDGRID_API_KEY=SG.xxx \
claude
```
> [!CAUTION]
> Only use test/development API keys in sandboxes, never production keys.
Loading from .env files:
Sandboxes don't automatically load `.env` files from your workspace, but you can ask Claude to use them:
```plaintext
You: "Load environment variables from .env.development and start the server"
```
Claude can use `dotenv` tools or source the file directly.
## Volume mounting
Mount additional directories or files to share data beyond your main workspace.
Use the `-v` flag with the syntax `host-path:container-path`:
```console
$ docker sandbox run -v ~/datasets:/data claude
```
This makes `~/datasets` available at `/data` inside the container. The agent
can read and write files in this location.
Read-only mounts:
Add `:ro` to prevent modifications:
```console
$ docker sandbox run -v ~/configs/app.yml:/config/app.yml:ro claude
```
Multiple mounts:
Use multiple `-v` flags to mount several locations:
```console
$ docker sandbox run \
-v ~/datasets:/data:ro \
-v ~/models:/models \
-v ~/.cache/pip:/root/.cache/pip \
claude
```
### Example: Machine learning workflow
Set up an ML environment with shared datasets, model storage, and persistent
caches:
```console
$ docker sandbox run \
-v ~/datasets:/data:ro \
-v ~/models:/models \
-v ~/.cache/pip:/root/.cache/pip \
claude
```
This provides read-only access to datasets (preventing accidental modifications),
read-write access to save trained models, and a persistent pip cache for faster
package installs across sessions.
Example conversation:
```plaintext
You: "Train a model on the MNIST dataset and save it to /models"
Claude: *runs*
python train.py --data /data/mnist --output /models/mnist_model.h5
```
### Common use cases
Shared configuration files:
```console
$ docker sandbox run -v ~/.aws:/root/.aws:ro claude
```
Build caches:
```console
$ docker sandbox run \
-v ~/.cache/go-build:/root/.cache/go-build \
-v ~/go/pkg/mod:/go/pkg/mod \
claude
```
Custom tools:
```console
$ docker sandbox run -v ~/bin:/shared-bin:ro claude
```
## Custom templates
Create custom sandbox templates to reuse configured environments. Instead of
installing tools every time you start an agent, build a Docker image with
everything pre-installed:
```dockerfile
# syntax=docker/dockerfile:1
FROM docker/sandbox-templates:claude-code
RUN <<EOF
curl -LsSf https://astral.sh/uv/install.sh | sh
. ~/.local/bin/env
uv tool install ruff@latest
EOF
ENV PATH="$PATH:~/.local/bin"
```
Build the image, and use the [`docker sandbox run --template`](/reference/cli/docker/sandbox/run#template)
flag to start a new sandbox based on the image.
```console
$ docker build -t my-dev-env .
$ docker sandbox run --template my-dev-env claude
```
### Using standard images
You can use standard Docker images as sandbox templates, but they don't include
agent binaries, shell configuration, or runtime dependencies that Docker's
sandbox templates provide. Using a standard Python image directly fails:
```console
$ docker sandbox run --template python:3-slim claude
The claude binary was not found in the sandbox; please check this is the correct sandbox for this agent.
```
To use a standard image, create a Dockerfile that installs the agent binary,
dependencies, and shell configuration on top of your base image. This approach
makes sense when you need a specific base image (for example, an exact OS
version or a specialized image with particular build tools).

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

@@ -0,0 +1,153 @@
---
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
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide covers authentication, configuration files, and common options for
running Claude Code in a sandboxed environment.
## Quick start
The simplest way to start Claude in a sandbox:
```console
$ docker sandbox run claude
```
This starts a sandboxed Claude Code agent with the current working directory as
its workspace.
Or specify a different workspace:
```console
$ docker sandbox run -w ~/my-project claude
```
## Passing CLI options to Claude
Claude Code supports various command-line options that you can pass through
`docker sandbox run`. Any arguments after the agent name (`claude`) are passed
directly to Claude Code inside the sandbox.
### Continue previous conversation
Resume your most recent conversation:
```console
$ docker sandbox run claude -c
```
Or use the long form:
```console
$ docker sandbox run claude --continue
```
### Pass a prompt directly
Start Claude with a specific prompt:
```console
$ docker sandbox run claude "Add error handling to the login function"
```
This starts Claude and immediately processes the prompt.
### Combine options
You can combine sandbox options with Claude options:
```console
$ docker sandbox run -e DEBUG=1 claude -c
```
This creates a sandbox with `DEBUG` set to `1`, enabling debug output for
troubleshooting, and continues the previous conversation.
### Available Claude options
All Claude Code CLI options work through `docker sandbox run`:
- `-c, --continue` - Continue the most recent conversation
- `-p, --prompt` - Read prompt from stdin (useful for piping)
- `--dangerously-skip-permissions` - Skip permission prompts (enabled by default in sandboxes)
- And more - see the [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) for a complete list
## Authentication
Claude sandboxes support the following credential management strategies.
### Strategy 1: `sandbox` (Default)
```console
$ docker sandbox run claude
```
On first run, Claude prompts you to enter your Anthropic API key. The
credentials are stored in a persistent Docker volume named
`docker-claude-sandbox-data`. All future Claude sandboxes automatically use
these stored credentials, and they persist across sandbox restarts and deletion.
Sandboxes mount this volume at `/mnt/claude-data` and create symbolic links in
the sandbox user's home directory.
> [!NOTE]
> If your workspace contains a `.claude.json` file with a `primaryApiKey`
> field, you'll receive a warning about potential conflicts. You can choose to
> remove the `primaryApiKey` field from your `.claude.json` or proceed and
> ignore the warning.
### Strategy 2: `none`
No automatic credential management.
```console
$ docker sandbox run --credentials=none claude
```
Docker does not discover, inject, or store any credentials. You must
authenticate manually inside the container. Credentials are not shared with
other sandboxes but persist for the lifetime of the container.
## Configuration
Claude Code can be configured through CLI options. Any arguments you pass after
the agent name are passed directly to Claude Code inside the container.
Pass options after the agent name:
```console
$ docker sandbox run claude [claude-options]
```
For example:
```console
$ docker sandbox run claude --continue
```
See the [Claude Code CLI reference](https://docs.claude.com/en/docs/claude-code/cli-reference)
for a complete list of available options.
## Advanced usage
For more advanced configurations including environment variables, volume mounts,
Docker socket access, and custom templates, see
[Advanced configurations](advanced-config.md).
## Base image
The `docker/sandbox-templates:claude-code` image includes Claude Code with
automatic credential management, plus development tools (Docker CLI, GitHub
CLI, Node.js, Go, Python 3, Git, ripgrep, jq). It runs as a non-root `agent`
user with `sudo` access and launches Claude with
`--dangerously-skip-permissions` by default.
## Next Steps
- [Advanced configurations](advanced-config.md)
- [Troubleshooting](troubleshooting.md)
- [CLI Reference](/reference/cli/docker/sandbox/)

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

@@ -0,0 +1,94 @@
---
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.
weight: 20
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide will help you run Claude Code in a sandboxed environment for the first time.
## Prerequisites
Before you begin, ensure you have:
- Docker Desktop 4.50 or later
- A Claude Code subscription
## Run a sandboxed agent
Follow these steps to run Claude Code in a sandboxed environment:
1. Navigate to Your Project
```console
$ cd ~/my-project
```
2. Start Claude in a sandbox
```console
$ docker sandbox run claude
```
3. Authenticate: on first run, Claude will prompt you to authenticate.
Once you've authenticated, the credentials are stored in a persistent Docker
volume and reused for future sessions.
4. Claude Code launches inside the container.
## What just happened?
When you ran `docker sandbox run claude`:
- Docker created a container from a template image
- Your current directory was mounted at the same path inside the container
- Your Git name and email were injected into the container
- Your API key was stored in a Docker volume (`docker-claude-sandbox-data`)
- Claude Code started with bypass permissions enabled
The container continues running in the background. Running `docker sandbox run
claude` again in the same directory reuses the existing container, allowing the
agent to maintain state (installed packages, temporary files) across sessions.
## Basic commands
Here are a few essential commands to manage your sandboxes:
### List your sandboxes
```console
$ docker sandbox ls
```
Shows all your sandboxes with their IDs, names, status, and creation time.
### Remove a sandbox
```console
$ docker sandbox rm <sandbox-id>
```
Deletes a sandbox when you're done with it. Get the sandbox ID from `docker sandbox ls`.
### View sandbox details
```console
$ docker sandbox inspect <sandbox-id>
```
Shows detailed information about a specific sandbox in JSON format.
For a complete list of all commands and options, see the [CLI reference](/reference/cli/docker/sandbox/).
## Next Steps
Now that you have Claude running in a sandboxed environment, learn more about:
- [Authentication strategies](claude-code.md#authentication)
- [Configuration options](claude-code.md#configuration)
- [Advanced configurations](advanced-config.md)
- [Troubleshooting guide](troubleshooting.md)

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

@@ -0,0 +1,121 @@
---
title: Troubleshooting
description: Resolve common issues when sandboxing agents locally.
weight: 50
---
{{< summary-bar feature_name="Docker Sandboxes" >}}
This guide helps you resolve common issues when sandboxing Claude Code locally.
<!-- vale off -->
## 'sandbox' is not a docker command
<!-- vale on -->
When you run `docker sandbox`, you see an error saying the command doesn't exist.
This means the CLI plugin isn't installed or isn't in the correct location. To fix:
1. Verify the plugin exists:
```console
$ ls -la ~/.docker/cli-plugins/docker-sandbox
```
The file should exist and be executable.
2. If using Docker Desktop, restart it to detect the plugin.
## "Experimental Features" needs to be enabled by your administrator
You see an error about beta features being disabled when trying to use sandboxes.
This happens when your Docker Desktop installation is managed by an
administrator who has locked settings. If your organization uses [Settings Management](/enterprise/security/hardened-desktop/settings-management/),
ask your administrator to [allow beta features](/enterprise/security/hardened-desktop/settings-management/configure-json-file/#beta-features):
```json
{
"configurationFileVersion": 2,
"allowBetaFeatures": {
"locked": false,
"value": true
}
}
```
## Authentication failure
Claude can't authenticate, or you see API key errors.
The API key is likely invalid, expired, or not configured correctly. How to fix depends on your credential mode:
If using `--credentials=sandbox` (the default):
1. Remove the stored credentials:
```console
$ docker volume rm docker-claude-sandbox-data
```
2. Start a new sandbox and complete the authentication workflow:
```console
$ docker sandbox run claude
```
## Workspace contains API key configuration
You see a warning about conflicting credentials when starting a sandbox.
This happens when your workspace has a `.claude.json` file with a `primaryApiKey` field. Choose one of these approaches:
- Remove the `primaryApiKey` field from your `.claude.json`:
```json
{
"apiKeyHelper": "/path/to/script",
"env": {
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}
```
- Or proceed with the warning - workspace credentials will be ignored in favor of sandbox credentials.
## Permission denied when accessing workspace files
Claude or commands fail with "Permission denied" errors when accessing files in the workspace.
This usually means the workspace path isn't accessible to Docker, or file permissions are too restrictive.
If using Docker Desktop:
1. Check File Sharing settings at Docker Desktop → **Settings** → **Resources** → **File Sharing**.
2. Ensure your workspace path (or a parent directory) is listed under Virtual file shares.
3. If missing, click "+" to add the directory containing your workspace.
4. Restart Docker Desktop.
For all platforms, verify file permissions:
```console
$ ls -la <workspace>
```
Ensure files are readable. If needed:
```console
$ chmod -R u+r <workspace>
```
Also verify the workspace path exists:
```console
$ cd <workspace>
$ pwd
```

29
data/sandbox-cli/docker_sandbox_ls.yaml
View File

@@ -9,6 +9,17 @@ usage: docker sandbox ls
pname: docker sandbox
plink: docker_sandbox.yaml
options:
- option: no-trunc
value_type: bool
default_value: "false"
description: Don't truncate output
details_url: '#no-trunc'
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
@@ -56,6 +67,24 @@ examples: |-
abc123def
def456ghi
```
### Don't truncate output (--no-trunc) {#no-trunc}
```text
--no-trunc
```
By default, long sandbox IDs and workspace paths are truncated for readability. Use `--no-trunc` to display the full values:
```console
$ docker sandbox ls
SANDBOX ID TEMPLATE NAME WORKSPACE STATUS CREATED
abc123def456 ubuntu my-project /home/user/.../my-project running 2 hours ago
$ docker sandbox ls --no-trunc
SANDBOX ID TEMPLATE NAME WORKSPACE STATUS CREATED
abc123def456ghi789jkl ubuntu my-project /home/user/very/long/path/to/my-project running 2 hours ago
```
deprecated: false
hidden: false
experimental: false

16
data/sandbox-cli/docker_sandbox_run.yaml
View File

@@ -82,6 +82,7 @@ options:
value_type: string
description: |
Container image to use for the sandbox (default: agent-specific image)
details_url: '#template'
deprecated: false
hidden: false
experimental: false
@@ -212,6 +213,21 @@ examples: |-
$ docker sandbox run --credentials host claude
```
### Use a custom base image (-t, --template) {#template}
```text
--template IMAGE
```
Specify a custom container image to use as the sandbox base:
```console
$ docker sandbox run --template python:3-alpine claude
```
By default, each agent uses a pre-configured image. The `--template` option
lets you substitute a different image.
### Name the sandbox (--name) {#name}
```text

3
data/summary.yaml
View File

@@ -186,6 +186,9 @@ Docker MCP Toolkit:
availability: Beta
Docker Projects:
availability: Beta
Docker Sandboxes:
availability: Experimental
requires: Docker Desktop [4.50](/manuals/desktop/release-notes.md#4500) or later
Docker Scout exceptions:
availability: Experimental
requires: Docker Scout CLI [1.15.0](/manuals/scout/release-notes/cli.md#1150) and later