docker-sandboxes-lifecycle

Docker Sandboxes：本地生命周期与工作区隔离

概述

Docker Sandboxes（sbx）会在隔离的微型虚拟机中运行 AI 编码 Agent，并为其提供独立的文件系统、网络和 Docker 守护进程。此技能负责本地沙箱生命周期——创建、重新连接、列出、停止和删除沙箱——以及工作区隔离方式（直接绑定挂载与 --clone）。不涵盖网络策略、凭据、sbxenv.yaml 或套件编写——请参阅相关技能。

何时使用此技能

在以下情况下启用此技能：

• 用户想要启动、重新连接到、停止或删除本地 sbx 沙箱。
• 用户希望 Agent 在仓库中工作，但不想向其提供主机工作树的可写绑定挂载（--clone）。
• 用户希望在主工作区旁挂载额外的只读（或限制写入）工作区。
• 用户要在主机与沙箱之间复制文件、发布沙箱端口，或在沙箱内运行临时命令（sbx exec）。
• 用户希望清理已停止的沙箱（sbx prune）或删除特定沙箱（sbx rm），并已了解这些操作的破坏性后果。

不要在以下情况下使用此技能

在以下情况下不要使用此技能：

• 任务是运行 docker agent run --sandbox 或管理其 docker agent sandbox 允许列表——请使用 docker-agent-run。如果 CLI 不明确，请先确认用户运行的是 Docker Agent 还是独立的 sbx，再选择命令。
• 任务涉及沙箱可访问的网络资源，或沙箱使用的凭据——请使用 docker-sandboxes-network-credentials。
• 任务涉及编写或运行声明式 sbxenv.yaml 文件——请使用 docker-sandboxes-env。
• 任务涉及编写、打包、签名或组合套件 spec.yaml——请使用 docker-sandboxes-kits。
• 任务涉及 sbx --cloud（Docker Cloud Sandboxes）——这不在此技能集的范围内；本技能集仅涵盖本地守护进程。

核心指南

创建与运行

• 使用 sbx run AGENT [PATH...] 在单个步骤中按需创建沙箱并连接。使用 sbx create AGENT [PATH...] 创建但不连接，之后再使用 sbx run --name SANDBOX 连接。向 sbx run 传入 --detached/-d，即可打印沙箱 ID 并退出，不进入交互会话。

  sbx run shell                  # create (if needed) and attach, cwd mounted
  sbx create shell .             # create only, cwd mounted, do not attach
  sbx run --name my-sandbox       # reattach later
  

• AGENT 可以是内置名称（claude、codex、cursor、devin、docker-agent、gemini、opencode、shell），也可以是沙箱套件引用（本地目录、ZIP、git 或 OCI）。相对路径形式的本地套件引用必须是显式路径（./my-kit、相对于父目录的 .zip 路径）——单独的 my-kit 会被视为 Agent/沙箱名称，而不会被识别为当前工作目录旁的目录。
• 不同子命令省略路径的含义并不相同。 不带路径运行 sbx run claude 会挂载当前目录。不带路径运行 sbx create claude 则完全不挂载任何内容——此时 Agent 只能在容器自己的文件系统中工作。如果要为 Agent 提供工作区，使用 sbx create 时务必显式传入路径。
• 建议使用 --name 重新连接；单独使用位置名称仍然可用，但已弃用。 推荐使用 sbx run --name NAME（Agent 位置参数可选，可从沙箱自身的规范中读取）。sbx run NAME——即既不是已知 Agent 名称、也不是显式套件引用的位置参数——仍然接受为旧版重新连接简写形式，但会打印弃用警告（“sbx run NAME 已弃用；请改用 sbx run --name NAME”），并且可能会在未来版本中移除。请始终显式写出 --name，不要依赖旧版形式。

  sbx run --name existing-sandbox                 # reattach, agent read from spec
  sbx run claude --name existing-sandbox          # reattach, verify expected agent
  

工作区隔离：绑定挂载与 --clone

• 默认（绑定挂载）： 工作区路径会以读写方式挂载到沙箱内，并与主机上的路径相同。Agent 可以直接写入你的工作树。
• --clone（仅在创建时生效）： Agent 会在容器内运行，并使用主机 Git 仓库的私有克隆。主机仓库以只读方式挂载；Agent 的提交会落在容器内的克隆中，可通过主机上的 sandbox-<name> git remote 访问；从该远程仓库 fetch 或 pull 即可将提交取回。

  sbx create --clone --name demo claude .
  # on the host, later:
  git fetch sandbox-demo
  

• --clone 有实际的前置条件，会在创建时检查，任何一项不满足都会明确报错：
  • 必须显式提供 PATH（必须有可供克隆的工作区）；
  • 该路径必须位于 Git 仓库内；
  • 该路径不能是 Git 工作树（容器内的克隆无法沿着工作树的 .git 指针访问其他位置的公共目录）；
  • 其 .git 必须是真实目录，而不能是文件（子模块或 --separate-git-dir 设置会使 .git 指向其他位置，而只读源挂载不会包含该位置）。
• 重新连接时，在 sbx run 上使用 --clone，只有在沙箱创建时已启用克隆模式的情况下才是空操作——不会重新验证任何内容，只会继续使用现有的容器内克隆。重新连接到创建时未启用该选项的沙箱（普通绑定挂载沙箱）时传入 --clone，并非静默空操作：它会报错并提示你使用 sbx create --clone ... 重新创建沙箱。无论哪种情况，都无法在创建后更改现有沙箱的模式。
• 移除或清理克隆模式沙箱，会永久丢弃 Agent 所做的所有尚未取回到主机的提交——容器内的克隆位于沙箱自己的文件系统中，会随沙箱一同删除。移除克隆模式沙箱前，请先 fetch 其工作成果：

  git fetch sandbox-demo
  

  Fetch 会填充两个 refspec：常规的 refs/remotes/sandbox-demo/*（沙箱移除时会与远程仓库一同删除），以及保留副本 refs/sandboxes/demo/*（位于远程命名空间之外，因此远程仓库删除后不会一同删除）。移除后，可通过以下命令从保留副本恢复分支：

  git branch <local-name> refs/sandboxes/demo/<branch>
  

  对于即将移除的任何克隆模式沙箱，sbx rm/sbx prune 都会自动打印此警告；确认前请先阅读，不要习惯性地使用 --force 忽略警告。
• 其他工作区是首个路径之后的额外位置参数。在挂载路径后追加 :ro，即可将其设为只读。:ro 只阻止写入，不阻止读取——沙箱仍能读取 :ro 挂载下的所有文件；这不是隐藏敏感内容的方式，只能阻止沙箱修改这些内容。只读参数也可以指定单个文件，而非目录；这样，沙箱在其他可写工作区中仍可访问该文件，但无法写入该路径。

  sbx run claude . /path/to/docs:ro
  

  切勿用这种方式挂载密钥/凭据文件（无论是否使用 :ro）——只读挂载仍会让沙箱（以及通过沙箱运行的、不经代理的 Agent 进程）以明文读取密钥。请改用凭据存储；参见 docker-sandboxes-network-credentials。

重新连接、停止和移除

• sbx ls 列出沙盒及其 Agent、状态、已发布端口和工作区（--json、-q/--quiet 可用于脚本）。
• sbx stop SANDBOX [SANDBOX...] 停止沙盒但不移除；状态会保留，使用 sbx run --name 可重启沙盒。
• sbx rm [SANDBOX...] [--all] [--force] 移除沙盒及其容器、Git 工作树、状态和沙盒范围内的密钥。此操作无法撤销；对于克隆模式的沙盒，还会丢弃所有尚未获取的提交（见上文）。只有在已检查将被销毁的内容并表示同意后才使用 --force——它适用于以脚本方式清理本次会话自行创建且名称唯一的资源，不应作为默认习惯。
• sbx prune [--dry-run] [--filter until=VALUE] [--force] 只移除已停止的沙盒——运行中的沙盒绝不会受到影响——但这仍是具有破坏性且不可逆的批量移除操作：每个符合条件的已停止沙盒，其状态、密钥以及（对于克隆模式的沙盒）任何尚未获取的提交都会被删除。务必先使用 --dry-run 预览，并阅读它打印的克隆提交警告，然后再实际移除；不要默认传入 --force。
  • 当前源码中的标志是 --filter until=VALUE，而不是 since=。VALUE 可以是 RFC 3339 时间戳、Unix 时间戳，或相对于当前时间的 Go 时长（例如，until=168h 会保留过去一周内停止的所有沙盒，也就是说，会清理在该时间点之前停止的沙盒）。这是固定提交版本中的仅源码行为，与某些已安装版本不同：较旧的已安装 sbx 可能仍会将 --filter since=DURATION 列为旧版别名；请优先使用 until=，如果已安装版本的 --help 输出中没有 until=，则将 since= 视为仅供旧版使用。

  sbx prune --dry-run --filter until=168h
  # after reviewing the dry-run output and any clone-commit warnings:
  sbx prune --filter until=168h
  

复制文件和运行临时命令

• sbx cp SRC DST 在主机和沙盒之间复制文件；其中一侧必须恰好是 SANDBOX:PATH。不支持在两个沙盒之间复制。

  sbx cp ./config.json my-sandbox:/home/agent/
  sbx cp my-sandbox:/home/agent/output.log ./
  

• sbx exec [flags] SANDBOX COMMAND [ARG...] 在沙盒中运行命令（如果沙盒已停止，则先启动）；标志与 docker exec 相同（-it、-d、-u、-w、-e、--env-file、--privileged）。

  sbx exec -it my-sandbox bash
  sbx exec -u root my-sandbox apt-get update
  

• sbx ports SANDBOX [--publish SPEC] [--unpublish SPEC] 在创建后管理已发布端口；sbx create/sbx run 上的 -p/--publish 仅在创建沙盒时生效，重新连接时不会生效。

资源配置和命名

• --cpus（0 = 自动：使用所有主机 CPU）和 --memory/-m（默认使用主机内存的 50%，限制在 512 MiB–32 GiB）只能在创建时设置。
• --name 设置沙盒名称（默认值为 <agent>-<workdir>）；名称至少为两个字符，以字母或数字开头，且只能包含字母、数字、连字符和句点；最多 63 个 ASCII 字符，并以字母或数字结尾；default 为保留名称。

相关技能

• 对于 docker agent run --sandbox 和 docker agent sandbox 命令，请使用 docker-agent-run。

• 对于网络出口策略以及服务/注册表凭据，请使用 docker-sandboxes-network-credentials。

• 对于声明式、纳入版本控制的 sbxenv.yaml 环境（用于封装相同的 create/run/rm 生命周期），请使用 docker-sandboxes-env。

• 对于编写或组合 kit spec.yaml（AGENT 引用可指向该文件），请使用 docker-sandboxes-kits。

参考资料

• references/sources.md — 上述每条规则的来源记录（帮助信息截取、源码路径、文档 URL）。

资源

• 无。

检查

• checks/verification.md — 沙盒生命周期命令的验证操作手册（尚未执行；请使用独立的 --app-name 手动运行，除非已同意清理操作手册自身创建且名称唯一的测试沙盒，否则绝不要使用 --force）。