Docker Sandboxes

工具 Mixin 往已有工作负载中添加一个可执行文件及其所需的设置。本教程把 Claude Code 打包成 Mixin，把它加到一个 shell 工作负载，并测试一次对 Anthropic API 的请求。沙箱启动一个 shell，由你决定何时运行 Claude Code。

这个示例改编自上游的 Claude Code Mixin，改用 API 密钥认证。上游示例还包含 OAuth、会话存储和 MCP 配置。

你需要 sbx、带 Buildx 的 Docker，以及一个 Anthropic API 密钥。要发布该 Mixin，还需要一个可以推送的镜像仓库命名空间。请把该 Mixin 与 v3 工作负载一起使用。shell 和 claude 这样的内置快捷方式使用 v3。请参阅 版本兼容性。

打包可执行文件 ​

创建一个 claude-mixin 目录，包含一个 Dockerfile 和一个 YAML 描述符：

text
claude-mixin/
├── claude-mixin.dockerfile
└── claude-mixin.yaml

Dockerfile 在构建阶段下载原生的 Claude Code 可执行文件，然后把它复制进一个空镜像：

dockerfile
FROM debian:trixie-slim AS build
ARG CLAUDE_VERSION
ARG TARGETARCH
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
RUN case "$TARGETARCH" in \
      amd64) platform=linux-x64 ;; \
      arm64) platform=linux-arm64 ;; \
      *) echo "unsupported TARGETARCH: $TARGETARCH" >&2; exit 1 ;; \
    esac \
    && mkdir -p /out/usr/local/bin \
    && curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_VERSION}/${platform}/claude" \
        -o /out/usr/local/bin/claude \
    && chmod 0755 /out/usr/local/bin/claude

FROM scratch
COPY --from=build /out/ /

BuildKit 会提供 TARGETARCH，用于选择与镜像 Linux 架构对应的下载文件。你会在描述符中设置 CLAUDE_VERSION。最后一个阶段只包含可执行文件，因此该 Mixin 不会把 Debian 或下载工具带进工作负载。

Docker Sandboxes 会把 Mixin 的文件加入工作负载的环境。工作负载保留自己的启动命令、用户和工作目录。这个示例使用 Docker 的 shell 工作负载。换用其他工作负载时，请确认它提供了你的工具所需的 Linux 库和 shell。

Mixin 只包含其 Dockerfile 添加或修改的文件。如果你使用比 scratch 更大的基础镜像，该 Mixin 不会包含那个镜像中未改动的文件。

声明运行时访问 ​

创建描述符，写明要安装的版本以及 Claude Code 所需的 API 访问：

yaml
# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: mixin
displayName: Claude Code mixin

args:
  version:
    default: "2.1.278"
    pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
    buildArg: CLAUDE_VERSION

provides: ["claude@${{ kit.args.version }}"]

capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - api.anthropic.com:443
  - type: com.docker.sandbox/credential@1
    config:
      service: anthropic
      phase: runtime
      apiKey:
        name: ANTHROPIC_API_KEY
        proxyManaged: true
        inject:
          - domain: api.anthropic.com
            header: x-api-key
            format: "%s"

version 参数向 Dockerfile 提供 CLAUDE_VERSION。provides 条目标识所安装的 Claude Code 版本，让其他 Kit 可以核对各自的需求。

网络规则允许对 Anthropic API 发起 HTTPS 请求。凭据条目申请存放在宿主上 anthropic 名下的密钥。在沙箱内部，ANTHROPIC_API_KEY 中是一个占位符。当 Claude Code 调用该 API 时，宿主代理会把真正的密钥插入 x-api-key 请求头。

网络访问和凭据访问是两回事：声明凭据并不等于允许连接它对应的服务。这个示例把 phase: runtime 与 runtime.allow 配对使用。Dockerfile 中的下载使用构建器的网络，不需要在描述符中加规则。

把工具的访问需求留在 Mixin 里，这样它与其他工作负载一起使用时仍然跟随它。项目工具共享的访问权限，比如包镜像仓库，可以放在 Kit 集合中。

试用 Mixin ​

把你的 Anthropic API 密钥存在宿主机上：

console
$ sbx secret set anthropic

在包含 claude-mixin 的目录中，把该 Mixin 加到 Docker 已发布的 shell 工作负载上：

console
$ sbx run shell --name claude-mixin-test \
    --kit ./claude-mixin

在提示时批准该 Mixin 的凭据申请。sbx 会构建这个 Mixin，把它的可执行文件加入工作负载，并打开一个 shell。该 Mixin 不会取代工作负载的启动命令。

在沙箱内部，检查 Claude Code 能否运行：

console
$ claude --version

然后发送一次请求，检查网络访问和身份验证。这条命令会使用 Anthropic API，并产生用量费用：

console
$ claude -p "Reply with the word hello."

有响应说明 Claude Code 能够访问该 API，并用你存储的密钥完成身份验证。如果身份验证失败，检查你是否存储了密钥并批准了该 Kit 使用它的请求。请参阅 凭据绑定。 网络请求还必须满足沙箱的网络策略，该策略把 Mixin 的网络规则与开发者自己的规则合并在一起。更多细节请参阅 规则如何合并。

不带参数运行 claude 可开始一个交互式会话。按它的首次运行提示操作。退出 Claude Code 和 shell，即可回到你的宿主。

编辑 Kit 的文件之后，用不同的名称创建沙箱来测试你的改动。重新打开已有沙箱会使用它创建时的那些 Kit。

发布 Mixin ​

构建并发布该 Mixin，让别人不必从源码构建就能使用：

console
$ docker login
$ docker buildx build ./claude-mixin -f ./claude-mixin/claude-mixin.yaml \
    -t docker.io/<NAMESPACE>/claude-mixin:1.0.0 --push

把 <NAMESPACE> 换成你可以推送的 Docker Hub 命名空间。用发布后的引用替换 ./claude-mixin 传给 --kit。

选择一个本身不提供 Claude Code 的工作负载。两个在 provides 中声明相同功能的 Kit 会冲突。要把 shell 工作负载和这个 Mixin 作为单个 Kit 分享，请参阅 编写 Kit 集合。

更多源码示例 ​

sandbox-kit-spec 示例包含可供研究和改编的完整 Kit：

  • Claude Code Mixin 包含额外的认证选项、会话存储和智能体说明。
  • GitHub CLI 打包 gh 及其依赖，并带上网络规则、凭据和智能体说明。
  • Message of the day 在单文件 Mixin 中使用内联 Dockerfile 和构建参数。

有关从源码构建工具、运行安装脚本等可复用做法，请参阅 Kit 编写模式。