基础镜像为你的工作负载提供操作系统和初始工具集。Docker 提供了已经装好智能体的镜像。你也可以从另一个 Linux 镜像开始，自己动手准备。在工作负载的 Dockerfile 中选择基础镜像。用 Kit 描述符配置网络访问、凭据和其他沙箱行为。Kit 集合使用其工作负载的基础镜像。

要保存并复用你交互式配置好的环境，请参阅 把沙箱保存为模板。

Docker 提供的镜像

内置智能体名会解析到 docker.io/sbx/<NAME>:latest 下的 Debian 系 Kit。要给这些智能体添加工具，请使用 Mixin。

这里介绍的 docker/sandbox-templates 镜像属于较旧的基于 Ubuntu 的镜像，与内置 Kit 相互独立。

要定制已有的智能体，请从 Docker 的沙箱模板之一开始，它以 docker/sandbox-templates:<variant> 发布。它们基于 Ubuntu，以非 root 的 agent 用户运行，并拥有 sudo 权限。大多数变体包含 Git、Docker CLI 以及 Node.js、Python、Go、Java 等常用开发工具。完整模板还包含用于构建原生代码的 C/C++ 编译器工具链。

变体	智能体
claude-code	Claude Code
claude-code-minimal	精简工具集的 Claude Code（不含 Node.js、Python、Go 或 Java）
codex	OpenAI Codex
copilot	GitHub Copilot
cursor-agent	Cursor
devin	Devin CLI
docker-agent	Docker Agent
droid	Droid
kiro	Kiro
opencode	OpenCode

Docker 会重新构建 claude-code、claude-code-minimal、gemini、claude-code-docker 和 gemini-docker 这几个变体。表中的其他变体仍以此前发布的镜像形式提供。

在 shell 镜像上构建自定义智能体

要打包一个 Docker 没有提供的智能体，请从 docker.io/sbx/shell-image:latest 开始。这个基础镜像提供了不带预装智能体的开发环境，你可以在其上添加自己的智能体工具。如果你的工作负载需要在沙箱内使用 Docker Engine，请改用 docker.io/sbx/shell-docker-image:latest。

如果你需要其他操作系统，或者想自己选择每一个软件包，请 使用你自己的 Linux 镜像。你需要自行准备 Docker Sandboxes 所要求的工具和用户账户。

在 v3 工作负载中使用镜像

用 FROM 开始你的工作负载 Dockerfile，然后添加需要的工具和配置。以 root 安装系统包，在往智能体主目录安装工具之前切换回 agent。以 root 运行那些安装程序会把文件放在 /root/ 下，智能体无法使用它们。

基础镜像提供了什么

FROM 会继承该镜像的文件和设置。如果该镜像同时也是一个已发布的 Kit，它的能力不会随之继承。在你自己的描述符中声明网络访问、凭据、存储和钩子。要保留已有 Kit 的能力并添加工具，请编写 Kit 集合。

你的描述符决定 Kit 格式版本。v3 描述符创建的是 v3 Kit，即使你用 Docker 模板镜像作为它的基础也一样。请参阅 版本兼容性。

打包已有的智能体镜像

这个例子把 Docker 的 OpenCode 镜像打包为 v3 工作负载。该镜像已经装好智能体，因此你只需选择它的启动命令，并描述运行它需要什么。构建出的 Kit 可以直接运行，也可以放进集合中并附带额外工具。

创建一个包含下面两个文件的目录：

opencode-workload/
├── opencode-workload.yaml
└── opencode-workload.dockerfile

Dockerfile 选择基础镜像，并指示 Docker Sandboxes 以 agent 用户运行 OpenCode：

FROM docker/sandbox-templates:opencode
USER agent
ENTRYPOINT ["opencode"]
CMD []

该模板提供 OpenCode、Python、uv 和 agent 用户。创建一个 YAML 描述符，标识这是一个工作负载，并声明 OpenCode 需要什么：网络访问、一个 Anthropic API 密钥，以及关于其环境的说明：

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: workload

capabilities:
  - type: com.docker.sandbox/sbx@1
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - api.anthropic.com
          - opencode.ai
          - models.dev
          - registry.npmjs.org
          - pypi.org
          - files.pythonhosted.org
  - 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"
  - type: com.docker.sandbox/agent-context@1
    config:
      filename: AGENTS.md
      content: |
        OpenCode runs as the agent user. Python and uv are available.
        Use the project's environment and dependency configuration.

凭据条目指明服务名称，并描述如何对 API 请求进行身份验证。把真正的 API 密钥存在宿主机上。

创建沙箱时，sbx 可以构建这个目录。构建结果是一个包含 Kit 文件和描述符的容器镜像，你也可以把它发布到镜像仓库供他人使用。

使用你自己的 Linux 镜像

如果你需要不同的操作系统或软件包集合，就从你选择的 Linux 镜像开始。你需要添加 Docker Sandboxes 所期望的工具和用户账户，然后安装你的智能体。

下面的要求帮助你准备该镜像。要看逐步的示例，请跟随 构建智能体工作负载。

基础镜像要求

按下面的要求准备镜像：

• 工具：包含 curl、git 以及访问源码仓库和发起 HTTPS 请求所需的受信任 CA 证书。
• Shell：提供可执行的 /bin/sh 和 /bin/bash，供安装命令和智能体启动使用。
• 用户账户：创建一个 UID 为 1000、主目录为 /home/agent 的非 root agent 账户。把该账户加入 /etc/passwd，并在镜像中设置 USER agent。
• 启动命令：把 ENTRYPOINT 或 CMD 设为你希望沙箱启动的智能体或 shell。

Docker Sandboxes 使用该账户在 /etc/passwd 中的条目，来确定运行命令和写文件时的用户 ID、组 ID 和主目录。

对于挂载了工作区的沙箱，WORKDIR 并不决定挂载位置。对于没有挂载工作区的沙箱，sbx 会把镜像中的绝对 WORKDIR 作为工作目录。如果镜像没有指定可用的绝对路径，sbx 会回退到 /home/agent/workspace。

声明智能体启动约定

sbx 保持沙箱运行，并把智能体作为独立进程启动，使用镜像的启动命令。com.docker.sandbox/sbx@1 能力声明你的工作负载已准备好以这种方式运行：

capabilities:
  - type: com.docker.sandbox/sbx@1

该能力不需要 config，也不申请额外权限。它让上游的一致性测试可以在你发布之前检查镜像是否满足 shell 和用户账户的要求。

宿主通过非交互式 Bash 启动智能体。要在启动时加载持久化的环境设置，把 BASH_ENV 设为一个绝对路径，并把该文件包含进镜像。Bash 会读取这个文件，而不是登录配置文件或 .bashrc。

完整的约定请参阅上游的 sbx@1 定义。