高级配置

Table of contents

Availability: Experimental

Requires: Docker Desktop 4.50 or later

本指南介绍在本地运行的沙箱代理的高级配置。

管理沙箱

重新创建沙箱

由于Docker强制每个工作空间只能有一个沙箱，因此每次在给定目录中运行docker sandbox run <agent>时，都会重用同一个沙箱。要创建新的沙箱，您需要先删除现有的沙箱：

$ docker sandbox ls  # 查找沙箱ID
$ docker sandbox rm <sandbox-id>
$ docker sandbox run <agent>  # 创建新沙箱

何时重新创建沙箱

沙箱会记住其初始配置，不会从后续的docker sandbox run命令中获取更改。您必须重新创建沙箱才能修改：

环境变量（-e标志）
卷挂载（-v标志）
Docker套接字访问（--mount-docker-socket标志）
凭据模式（--credentials标志）

列出和检查沙箱

查看所有沙箱：

$ docker sandbox ls

获取特定沙箱的详细配置信息：

$ docker sandbox inspect <sandbox-id>

这将显示沙箱的配置，包括环境变量、卷和创建时间。

删除沙箱

删除特定沙箱：

$ docker sandbox rm <sandbox-id>

一次性删除所有沙箱：

$ docker sandbox rm $(docker sandbox ls -q)

这在完成项目或想要重新开始进行清理时非常有用。

授予代理Docker访问权限

挂载Docker套接字以授予代理在容器内访问Docker命令的权限。代理可以构建镜像、运行容器并使用Docker Compose设置。

Caution

挂载Docker套接字授予代理对Docker守护进程的完全访问权限，该守护进程在您的系统上具有root级权限。代理可以启动或停止任何容器、访问卷，并可能逃离沙箱。仅当您完全信任代理正在处理的代码时才使用此选项。

启用Docker套接字访问

使用--mount-docker-socket标志：

$ docker sandbox run --mount-docker-socket claude

这将把主机的Docker套接字（/var/run/docker.sock）挂载到容器中，授予代理访问Docker命令的权限。

Important

代理可以看到并与主机上的所有容器交互，而不仅仅是沙箱内创建的容器。

示例：测试容器化应用程序

如果您的项目有Dockerfile，代理可以构建并测试它：

$ cd ~/my-docker-app
$ docker sandbox run --mount-docker-socket claude

示例对话：

您："构建Docker镜像并运行测试"

Claude: *运行*
  docker build -t myapp:test .
  docker run myapp:test npm test

代理使用Docker套接字访问可以做什么

启用Docker访问后，代理可以：

使用Docker Compose启动多容器应用程序
为多种架构构建镜像
管理主机上的现有容器
验证Dockerfile并测试构建过程

环境变量

使用-e标志传递环境变量以配置沙箱环境：

$ docker sandbox run \
  -e NODE_ENV=development \
  -e DATABASE_URL=postgresql://localhost/myapp_dev \
  -e DEBUG=true \
  claude

这些变量可用于容器中的所有进程，包括代理及其运行的任何命令。使用多个-e标志设置多个变量。

示例：开发环境设置

设置完整的开发环境：

$ 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

示例对话：

您："运行数据库迁移并启动开发服务器"

Claude: *使用DATABASE_URL和其他环境变量*
  npm run migrate
  npm run dev

常见用例

测试API密钥：

$ docker sandbox run \
  -e STRIPE_TEST_KEY=sk_test_xxx \
  -e SENDGRID_API_KEY=SG.xxx \
  claude

Caution

在沙箱中仅使用测试/开发API密钥，切勿使用生产密钥。

从.env文件加载：

沙箱不会自动从工作区加载.env文件，但您可以要求Claude使用它们：

您："从.env.development加载环境变量并启动服务器"

Claude可以使用dotenv工具或直接获取文件。

卷挂载

挂载其他目录或文件以共享主工作区之外的数据。使用-v标志和语法host-path:container-path：

$ docker sandbox run -v ~/datasets:/data claude

这会使~/datasets在容器内的/data位置可用。代理可以读写此位置的文件。

只读挂载：

添加:ro以防止修改：

$ docker sandbox run -v ~/configs/app.yml:/config/app.yml:ro claude

多个挂载：

使用多个-v标志挂载多个位置：

$ docker sandbox run \
  -v ~/datasets:/data:ro \
  -v ~/models:/models \
  -v ~/.cache/pip:/root/.cache/pip \
  claude

示例：机器学习工作流

设置具有共享数据集、模型存储和持久缓存的ML环境：

$ docker sandbox run \
  -v ~/datasets:/data:ro \
  -v ~/models:/models \
  -v ~/.cache/pip:/root/.cache/pip \
  claude

这提供了对数据集的只读访问（防止意外修改）、对保存训练模型的读写访问，以及持久pip缓存，以便在会话之间更快地安装包。

示例对话：

您："在MNIST数据集上训练模型并将其保存到/models"

Claude: *运行*
  python train.py --data /data/mnist --output /models/mnist_model.h5

常见用例

共享配置文件：

$ docker sandbox run -v ~/.aws:/root/.aws:ro claude

构建缓存：

$ docker sandbox run \
  -v ~/.cache/go-build:/root/.cache/go-build \
  -v ~/go/pkg/mod:/go/pkg/mod \
  claude

自定义工具：

$ docker sandbox run -v ~/bin:/shared-bin:ro claude

自定义模板

创建自定义沙箱模板以重用配置环境。与其每次启动代理时都安装工具，不如构建一个包含所有预安装内容的Docker镜像：

# 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"

构建镜像，并使用 docker sandbox run --template标志启动基于该镜像的新沙箱。

$ docker build -t my-dev-env .
$ docker sandbox run --template my-dev-env claude

使用标准镜像

您可以使用标准Docker镜像作为沙箱模板，但它们不包含Docker沙箱模板提供的代理二进制文件、shell配置或运行时依赖项。直接使用标准Python镜像会失败：

$ 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.

要使用标准镜像，请创建一个Dockerfile，在基础镜像之上安装代理二进制文件、依赖项和shell配置。当您需要的特定基础镜像（例如，确切的OS版本或具有特定构建工具的专业镜像）时，这种方法很有意义。