本页介绍 CI 中的本地沙箱。关于不使用本地虚拟化的云端执行，请参阅 Run without attaching。

在没有浏览器的 CI 环境和脚本中，使用 Docker Personal Access Token（PAT）认证：

$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin

从你的 Docker account settings 生成 PAT，权限至少需要 Read。

在运行需要认证的命令之前先登录。只读命令以及带 --force 运行的命令不会开启交互式 登录流程。在调用 sbx create 或 sbx run 之前先创建工作区目录：没有终端时，如果 工作区目录不存在，这些命令会失败。

用 sbx create 在后台创建沙箱，用 sbx exec 运行智能体任务，结束后移除沙箱：

$ sbx create --name ci-task --clone claude .
$ sbx exec ci-task -- claude --dangerously-skip-permissions -p "Review the code and commit your changes"
$ git fetch sandbox-ci-task
$ sbx rm --force ci-task

智能体凭据（API key、GitHub token）可以预先配置为全局机密，这样 CI runner 创建的 任何沙箱都能使用。如果相关环境变量已在 CI 环境中设置（每个服务读取哪些变量请参阅 built-in services table），可以 一次全部导入：

$ sbx secret import --all

要覆盖已有的存储条目，添加 --force。要从 CI 提供方的机密存储传值，使用 -t。 例如，在 GitHub Actions 的一个步骤中：

- run: sbx secret set anthropic --force -t "${{ secrets.ANTHROPIC_API_KEY }}"

清理与退出码

sbx exec 返回它所运行命令的退出状态。命令无法运行（例如沙箱不存在）时返回 125。 本地沙箱内缺少可执行文件时返回 127。在决定是否重试之前，先查看 stderr 了解原因。

确认操作需要终端输入。用管道给出回答（例如 echo y）并不构成确认。对支持该标志的 命令使用 --force，可以在脚本中跳过确认。对于 sbx logout，使用 --yes 或 -y， 即使没有本地 daemon 在运行也是如此。sbx kit builder history rm 同样使用 --yes 或 -y，因为它的 --force 标志会透传给 Buildx。

当 stdin 不是终端时，需要确认的命令会以退出状态 1 失败。拒绝确认同样会返回非零 退出码。判断脚本是否继续时，请把它视为操作未完成。

要做可重复的清理，先检查哪些资源存在，再删除它们。例如，在 sbx mcp rm 之前先用 sbx mcp ls 检查，即使加了 --force，未注册的服务器也会让该命令失败。同样地， 如果没有机密匹配选择器，sbx secret rm 会失败；移除机密前先用 sbx secret ls 检查是否存在匹配项。

解析命令输出

在支持结构化输出的命令上使用 --format json 或 --format yaml。人类可读的表格和 消息可能随版本变化。结果输出到 stdout。错误、警告、提示和进度输出到 stderr。

$ sbx ls --json | jq -r '.[].name'
$ sbx prune --dry-run --format yaml

--json 是 --format json 的别名。在共用输出标志的命令上，--format、--json 和 --quiet（-q）互斥，即使 --json 和 --format json 请求的是同一种格式。不支持的 格式值会被拒绝。sbx events --json 输出以换行分隔的 JSON，而 sbx mcp auth --format text|json 使用命令专属的格式。

对于不需要表头的标识符列表，使用 --quiet 或 -q：

命令	输出
sbx policy ls -q	本地规则 ID。使用 --cloud 时改为输出网络模式。
sbx settings ls -q	设置项键名。
sbx policy approval ls -q	审批 ID。

要抑制沙箱创建的进度输出，使用 sbx run --no-progress。命令结果仍会打印，包括 使用 --detach 时的沙箱 ID。

为 v0.48.0 更新脚本

复制为提示词

使用下面的迁移参考更新本仓库对 Docker Sandboxes CLI 的使用方式（目标版本 v0.48.0）。检查脚本与文档，更新受影响的命令与输出解析器，并验证改动。不要改变无关的行为。

Docker Sandboxes v0.48.0 更改了标志和结构化输出。请更新使用以下标志的脚本：

命令	原标志	替代方案
sbx run、sbx env run	--detached	--detach 或 -d
sbx env create、sbx env run	--auto-approve、-y	--force 或 -f
sbx create	--quiet、-q	--no-progress 抑制进度输出，但仍会打印创建摘要
sbx template save	用于描述的 -d	--description
sbx diagnose	--output、-o	--format table、json、yaml 或 github-issue
sbx policy log	--quiet、-q	已移除，没有替代项

sbx settings ls 是主要写法。sbx settings list 仍是别名。把已弃用的 sbx mcp add --skip_auth 替换为 --skip-auth。默认使用全局作用域的机密命令仍然 接受已弃用的 --global 标志，但会向 stderr 打印警告。这些命令请省略该标志。

JSON 字段名使用 snake_case。YAML 使用相同的表示形式。请更新以下命令的解析器：

命令	v0.48.0 中的结构化输出
sbx ls	沙箱数组，取代 {sandboxes: [...]}。created_at 和 last_used_at 使用 RFC 3339 时间戳。各行包含 detached。
sbx template ls	镜像数组，取代 {images: [...]}。
本地 sbx mcp ls	服务器数组，取代 {gateway: {...}, servers: [...]}。每一行都包含 gateway。云端行描述服务器在各沙箱中的使用情况，与本地注册行不同。
sbx policy log	本地和云端输出均为 {updated_at, allowed: [...], blocked: [...]}。请参阅 Get the log as JSON or YAML。
sbx --cloud policy ls	字段名使用 snake_case 而非 camelCase。
sbx ports	本地行包含 host_ip、host_port、sandbox_port 和 protocol。云端行包含 sandbox_port 和 url，取代 port。本地发布和取消发布的结果包含 action: published 或 action: unpublished。
云端 sbx volume create、sbx volume ls、sbx volume inspect	ID、Name、CreatedAt 等字段变为 id、name 和 created_at。volume inspect 默认输出人类可读的详情，因此需要显式请求结构化格式。
sbx rm、sbx stop、sbx template rm、sbx volume rm	结果数组，包含 action、resource、name，以及可选的 id 和 error，包括目标缺失或失败的情况。动作为小写：removed、stopped、removing、stopping 或 failed。

例如，从 sbx ls --json 提取沙箱名称时，把 jq 过滤器 .sandboxes[].name 换成 .[].name。