本页描述的是本地沙箱。有关云端命令、文件传输、端口和过期机制，请参阅 使用云端沙箱。

把本页作为日常 sbx 操作的命令速查手册。有关基于场景的建议，请参阅 工作流模式。有关脚本输出和 v0.48.0 CLI 迁移，请参阅 CI 与无界面使用。

登录

在终端中登录：

$ sbx login

对于没有浏览器的脚本或 CI 运行器，请参阅 CI 与无界面使用。

启动、停止和删除

基本工作流是用 run 启动、 ls 查看状态、 stop 暂停，以及用 rm 清理：

$ sbx run claude                    # 在当前目录中启动一个智能体
$ sbx ls                            # 查看正在运行的内容
$ sbx stop my-sandbox               # 暂停它
$ sbx rm my-sandbox                 # 完全删除它

sbx rm 在删除沙箱前会要求确认。使用 --force 可跳过该提示。这个标志还允许在 沙箱有活动会话时执行删除 —— 即一个打开的 attach 会话、SSH 连接或进行中的 SFTP 传输：

$ sbx rm --force my-sandbox

如果你需要重新开始，请删除沙箱后再次运行：

$ sbx stop my-sandbox
$ sbx rm my-sandbox
$ sbx run claude

要删除所有已停止的本地沙箱，使用 sbx prune。正在运行的沙箱永远不会被删除。 可以先预览将被删除的沙箱，或者过滤掉最近一周内停止的沙箱：

$ sbx prune --dry-run
$ sbx prune --filter until=168h

until 过滤器使用沙箱停止的时间。它接受诸如 168h 的时长、RFC 3339 时间戳 或 Unix 时间戳。较旧的 since=<duration> 过滤器仍然受支持。

不带任何标志运行 sbx prune 即可确认并删除所有已停止的沙箱。

智能体退出时删除沙箱

向 sbx run 传入 --rm 可开启一次性会话。智能体退出时沙箱会被删除，且不会 出现确认提示：

$ sbx run --rm claude

无论智能体以何种方式退出，沙箱都会被删除，并且 sbx run 会以智能体的退出状态 退出。如果 sbx run 创建了沙箱但智能体启动失败，沙箱同样会被删除。如果你使用 --rm 重新接入一个已有沙箱，该沙箱只会在其智能体会话结束后才被删除。

--rm 需要依附的智能体会话才能知道何时删除沙箱，因此不能与 --detach 或 --detach-keys 一起使用。

向智能体传递参数

把智能体标志、提示词和子命令放在 -- 之后。-- 之前的选项用于配置沙箱， 之后的参数则传给智能体：

$ sbx run claude -- "explain this project"
$ sbx run claude -- --model sonnet
$ sbx run --name my-project -- --model sonnet

不转发任何参数时，智能体会使用它默认的启动命令。如果转发的第一个参数是一个 标志（以 - 开头），启动器会保留默认值并追加你的参数。若要在传入提示词的同时 保留默认的权限标志，请把该标志放在前面：

$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"

如果你以提示词或子命令开头，它会替换默认的命令参数（CMD），但保留镜像的 entrypoint 参数（ENTRYPOINT）。如果 entrypoint 中包含子命令，请在传入提示词时 不要重复该子命令。

如需在不带上智能体启动默认值的情况下运行其他子命令，请在运行中的沙箱中用 sbx exec 直接运行该智能体。例如：

$ sbx exec -it <sandbox-name> <agent> <subcommand>

有关启动命令和各智能体特有的选项，请参阅智能体页面。

选择工作区

不传工作区路径时，sbx run 会挂载当前目录。传入路径则挂载另一个目录：

$ sbx run claude
$ sbx run claude ~/my-project

第一个工作区路径是主工作区。智能体从那里启动，sbx exec 也把它作为默认工作 目录。宿主机目录会以相同的绝对路径挂载到沙箱内。不向 sbx run 传入路径时， 当前目录就是主工作区。

从 sbx 0.42.0 版本开始，sbx create 的工作区路径是可选的。省略该路径可创建 一个没有宿主机工作区绑定挂载的无挂载沙箱，然后按名称接入该沙箱：

$ sbx create --name scratch claude
$ sbx run --name scratch

在无挂载沙箱中，智能体从模板镜像的工作目录启动。Docker 提供的模板使用 /home/agent/workspace。该目录下的文件在停止和重启后依然存在，但在你删除 沙箱时会被一并删除。为沙箱指定名称以便重新连接，并使用 sbx cp 在沙箱和宿主机之间传输文件。

重新连接并为沙箱命名

智能体退出后沙箱依然保留。再次使用同一个工作区路径运行会重新连接到已有沙箱， 而不是创建新沙箱：

$ sbx run claude ~/my-project  # 创建沙箱
$ sbx run claude ~/my-project  # 重新连接到同一个沙箱

使用 --name 为沙箱指定明确的身份标识：

$ sbx run --name my-project claude

一旦有了具名沙箱，你就可以从任意工作目录用 sbx run --name 重新接入。重新接入 时可以省略智能体名称：

$ sbx run --name my-project        # 从任意位置重新接入
$ sbx run claude --name my-project # 同上，并确认智能体

如需针对同一个工作区运行多个沙箱，请为它们分别指定不同的名称：

$ sbx run claude --name feature ~/my-project
$ sbx run claude --name spike ~/my-project

创建但不接入

sbx run 会创建沙箱并把你接入智能体。如需创建沙箱 并挂载当前目录但不接入：

$ sbx create --name my-project claude .

省略路径则创建一个无挂载沙箱。之后用 sbx run --name 接入：

$ sbx create --name scratch claude
$ sbx run --name scratch

sbx create 结束后，当没有会话维持其运行时，本地沙箱会自动停止。它的文件和 配置会保留。运行 sbx run --name <sandbox-name> 可再次启动它并把你接入智能体。

让沙箱在后台保持运行

若要讓沙箱在每个会话结束后继续运行，例如在已发布端口上提供 应用服务，请使用 sbx run --detach（-d）启动。该命令会启动沙箱、打印其 ID， 然后返回，不会打开智能体会话：

$ sbx run -d --name my-project claude .

分离运行的沙箱会一直运行，直到你用 sbx stop 停止它或用 sbx rm 删除它。 你可以用 sbx run --name 接入它，或用 sbx exec 运行命令，而这些会话结束后 沙箱仍会继续运行。

对已有沙箱（如用 sbx create 创建的沙箱）运行 sbx run -d --name <sandbox-name>， 会把它永久切换到分离模式。要恢复默认行为，请删除该沙箱后重新创建。

设置环境变量

NOTE

-e/--env 和 --env-file 标志需要 sbx 0.39.0 或更高版本。

向 sbx run 或 sbx create 传入 -e 或 --env，即可在沙箱中设置环境变量：

$ sbx run -e LOG_LEVEL=debug claude

只指定变量名而不指定值，则从宿主机环境中复制该变量的值：

$ export API_URL=https://api.example.com
$ sbx run -e API_URL claude

要加载多个变量，可以传入一个或多个环境文件：

$ sbx create --name my-project --env-file .env.sandbox claude .

这些标志遵循 docker run 的优先级规则。用 -e 传入的值会覆盖环境文件中的值。 当你传入多个环境文件时，后面的文件中的值会覆盖前面文件中的同名变量。

当其中一个命令创建沙箱时，这些变量会随沙箱一起存储。它们同样适用于 sbx run 启动的智能体会话。当 sbx run 重新接入已有沙箱时，这些变量只对该智能体会话 生效，不会改变沙箱中存储的环境。如需只为某一条命令设置变量，请使用 sbx exec -e 或 sbx exec --env-file。

如需让某个变量在已有沙箱的后续会话中持续生效，请把一条 export 语句追加到 /etc/sandbox-persistent.sh：

$ sbx exec <sandbox-name> bash -c "echo 'export INTERNAL_API_URL=https://api.example.com' >> /etc/sandbox-persistent.sh"

bash -c 包装确保 >> 重定向在沙箱内部执行，而不是在你的宿主机上执行。Bash 在 沙箱内启动时会加载该文件，包括交互式会话和通过 sbx run 启动的智能体。直接 传给 sbx exec 的命令不会启动 shell。如果该命令需要持久环境文件中的变量，请用 bash -c 包裹它。

添加到该文件的变量只对之后启动的会话和智能体生效。重启正在运行的智能体，或停止 并重新启动沙箱，即可应用新的值。

沙箱内的进程可以读取环境变量。对于 API 密钥和其他凭据，请对受支持的服务使用 sbx secret set，对要发送到已知 主机的凭据使用实验性的 sbx secret set-custom。这样 宿主机侧的代理就能在运行时注入真实值，而不会暴露给智能体。

在沙箱内运行命令

要在运行中的沙箱里获取 shell，请使用 sbx exec：

$ sbx exec -it <sandbox-name> bash

不加 --workdir 时，命令会在沙箱的主工作区中启动。在无挂载沙箱中，它会在 容器镜像的工作目录中启动。

sbx exec 在前台运行命令。不支持分离执行（-d 或 --detach）。本地的 sbx exec 和 sbx env exec 也会拒绝 --detach-keys。本地命令请省略该标志；它仅适用于 交互式的云端 exec 会话。

交互模式

不带子命令运行 sbx 会打开一个交互式终端仪表板：

$ sbx

仪表板以卡片形式展示你的所有沙箱，附带实时状态、CPU 和内存使用情况。在这里你可以：

• 创建沙箱（c）。
• 启动或停止沙箱（s）。
• 接入智能体会话（Enter），与 sbx run 相同。
• 在沙箱内打开 shell（x），与 sbx exec 相同。
• 删除沙箱（r）。

仪表板还包含一个网络治理面板，你可以在其中监控沙箱发出的出站连接并管理网络规则。 使用 tab 在沙箱面板和网络面板之间切换。

在网络面板中，你可以浏览连接日志、允许或阻止特定主机，并添加自定义网络规则。 按 ? 查看全部键盘快捷键。

在选择和文本输入提示中，按 Enter 接受默认值，Ctrl-D 取消提示。拒绝必需的确认会 返回非零退出状态。

Git 工作区模式

当你的主工作区是一个 Git 仓库时，需要在创建沙箱时选择沙箱以何种方式获取该仓库：

• 直接模式是 sbx run 的默认模式。当你向 sbx create 传入工作区路径时同样适用。 智能体对你的工作树拥有读写权限，改动会立即出现在你的宿主机上。
• 克隆模式使用 --clone。智能体在沙箱内编辑一份独立的 Git 克隆。 它的改动会留在那里，直到你把它们 fetch 回来或由智能体推送。你宿主机上的仓库 在 /run/sandbox/source 处同样可用，但只有读权限。

有关分支策略、从沙箱获取工作成果以及并行智能体工作流的指导，请参阅 Git 工作流。有关每种模式背后的安全模型，请参阅 工作区隔离。

克隆模式

要创建克隆模式的沙箱，请在运行或创建时传入 --clone：

$ sbx run --clone claude .

你也可以先在后台创建沙箱，之后再接入：

$ sbx create --clone --name my-sandbox claude .
$ sbx run --name my-sandbox

克隆模式在创建时有一些限制：

• 克隆模式在创建时确定。要把已有沙箱切换到克隆模式，请删除它并用 sbx create --clone 重新创建。
• 克隆会跟随你的宿主机仓库在创建时检出的那个 ref。不会自动创建分支。
• 主工作区必须是 Git 仓库。非 Git 工作区请省略 --clone。
• 在主检出之外的其他 Git worktree 中会拒绝克隆模式。只读绑定挂载无法解析该 worktree 的 .git 指针文件。请改为在主仓库检出中运行 sbx create --clone <agent> .。
• 删除克隆模式的沙箱会丢弃沙箱内的克隆。在删除之前，先 fetch 或 push 任何你想 保留的提交。

多个工作区

除主工作区外，你还可以把额外的目录挂载到沙箱中。第一个路径是主工作区 —— 智能体从那里启动，使用 --clone 时沙箱内的 Git 克隆也是从这个目录填充的。 额外的工作区始终以直接方式挂载。

默认情况下，每个直接挂载的工作区在沙箱内呈现的绝对路径与宿主机上相同。追加 :ro 可以把额外的工作区以只读方式挂载 —— 适用于智能体不应修改的参考资料或 共享库：

$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro

如需为额外的工作区指定沙箱内路径，请在使用 sbx run 或 sbx create 时使用 PATH:TARGET[:ro]：

$ sbx run claude ~/project-a ~/shared-libs:/workspace/libs:ro

这会把 ~/shared-libs 以只读方式挂载到沙箱内的 /workspace/libs。主工作区不 接受目标路径。

目标路径必须是不为 / 的绝对 POSIX 路径，且不能包含冒号或 NUL 字节。请为每个 额外的工作区选择互不相同的目标路径。目标路径不能与主工作区路径或保留的技能 路径相同。在克隆模式下，它们还必须位于克隆目录之外，且不能与 /run/sandbox/source 相同。

你也可以并行运行不同的项目。用完后删除不再使用的沙箱以回收磁盘空间：

$ sbx run claude ~/project-a
$ sbx run claude ~/project-b
$ sbx rm <sandbox-name>       # 完成后

在宿主机和沙箱之间复制文件

使用 sbx cp 在你的宿主机和沙箱之间复制文件或目录。 这对于不属于已挂载工作区的一次性文件很有用，例如生成的产物、日志或安装文件。 沙箱路径必须是绝对路径。sbx cp 不会把 . 之类的相对路径解析到沙箱的默认工作 目录。

例如，向 Docker 提供的智能体模板所使用的默认工作目录复制文件，或从该目录复制：

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

复制的一侧必须使用 SANDBOX:PATH 形式。不支持直接在两个沙箱之间复制。

发布端口

沙箱是网络隔离的 —— 默认情况下，你的浏览器或本地工具 无法访问运行在其中的服务器。8080:3000 这样的端口映射会把沙箱的 3000 端口 发布到宿主机的 8080 端口。

如果你清楚需要哪些端口，创建沙箱时就把它们发布出去：

$ sbx run --publish 8080:3000 --name my-sandbox claude

对于已有沙箱，使用 sbx ports 从你的宿主机转发 流量。在已停止的本地沙箱上发布端口会先把它启动：

$ sbx ports my-sandbox --publish 8080:3000
$ open http://localhost:8080

如需让操作系统自行挑选空闲的宿主机端口而不是由你指定，只写沙箱端口即可。然后 用 sbx ports 查看分配到的宿主机端口：

$ sbx ports my-sandbox --publish 3000
$ sbx ports my-sandbox

sbx ls 会在每个沙箱旁显示活动的端口映射。sbx ports 会详细列出它们。 CREATED 列显示沙箱的创建时长，STATUS 列则标识以分离模式保持运行的沙箱 （标注为 (detached)）。

$ sbx ls
SANDBOX      AGENT    STATUS      PORTS                       WORKSPACE         CREATED
my-sandbox   claude   ● running   127.0.0.1:8080->3000/tcp4    /home/user/proj    2m

要停止转发某个端口：

$ sbx ports my-sandbox --unpublish 8080:3000

当 sbx run 重新接入已有沙箱时，它会忽略 --publish。请用 sbx ports 在该沙箱 上发布端口。有关开发服务器和宿主机服务的用法示例，请参阅 本地服务。

哪些内容会保留

只要沙箱存在，已安装的软件包、Docker 镜像、配置变更、命令历史和无挂载工作区 中的文件都会在停止和重启后保留。删除沙箱会删除它的容器文件系统。宿主机上的 工作区文件（包括用作克隆源的仓库）以及 共享的智能体技能存储仍留在你的宿主机上。本地沙箱中的 持久化 Kit 卷在删除沙箱后同样会保留。有关如何重新挂载它们，请参阅 重新创建沙箱时保留 Kit 数据。

若要捕获容器文件系统中的改动，请保存为模板。 若要获得在源码中定义的可复现环境，请编写 Kit。

将沙箱保存为模板

在交互式地配置好工具或设置之后，可以把沙箱的容器文件系统保存为可复用的模板 镜像。模板包含镜像内容；运行时设置（如凭据和网络规则）仍由智能体 Kit 提供。 这里的示例复用了与内置智能体搭配的模板。

保存的模板并不是整个沙箱的备份。已挂载的文件系统，包括宿主机工作区和 /var/lib/docker 处的 Docker 存储，都不包含在内。请单独保存这些挂载点上的 数据。

WARNING

保存沙箱会捕获其容器文件系统中的文件，包括存放在那里的任何密钥。如果你手动 把 API 密钥、令牌或其他凭据添加到了沙箱中，它们会被嵌入保存的模板，并随模板 分发给任何拿到它的人。若要让凭据不进入模板，请改用 sbx secret set 管理 —— 代理会在运行时注入它们，因此它们永远不会被写入文件系统。更多信息请参阅 管理凭据。

保存并复用

停止沙箱（或让 CLI 提示你停止），然后带名称和标签保存它：

$ sbx template save my-sandbox my-template:v1

该镜像存储在沙箱运行时的本地镜像存储中。用 -t 标志从它创建新沙箱：

$ sbx run -t my-template:v1 claude

列出和删除模板

列出沙箱运行时本地镜像存储中带标签的模板镜像：

$ sbx template ls

删除不再需要的模板：

$ sbx template rm my-template:v1

如果你想删除的本地镜像没有出现在默认列表中，它可能没有标签。请包含不带标签的 镜像并显示它们的摘要：

$ sbx template ls --all --digests

使用列表中的镜像 ID 或仓库摘要删除该镜像：

$ sbx template rm <IMAGE_ID>

$ sbx template rm <REPOSITORY>@sha256:<DIGEST>

只要前缀能唯一标识某个模板，就可以使用镜像 ID 的前缀。--all 和 --digests 标志仅适用于本地模板。有关全部列表选项，请参阅 sbx template ls 参考。

导出和导入

如需共享已保存的模板或把它迁移到另一台机器，请将其导出为 tar 文件：

$ sbx template save my-sandbox my-template:v1 --output my-template.tar

在另一台机器上，加载该 tar 文件并使用它：

$ sbx template load my-template.tar
$ sbx run -t my-template:v1 claude

限制

创建沙箱时，智能体配置文件总是会被重新创建。对用户级智能体配置文件（如 /home/agent/.claude/settings.json 和 /home/agent/.claude.json）所做的修改， 不会保留在保存的模板中。

如果保存的模板是为另一个智能体构建的，而你却在 sbx run 中指定了不同的智能体， CLI 会向 stderr 打印一条警告并给出建议的命令。例如，保存一个 Claude 沙箱后用 codex 运行它，会提示使用 sbx run -t my-template:v1 claude。

加载模板

要从镜像仓库中的模板镜像创建沙箱，请把完整的镜像引用传给 --template。请使用 该镜像所针对的智能体：

$ sbx run --template docker.io/my-org/my-template:v1 claude

与 Docker 命令不同，sbx 不会自动把 Docker Hub 域名（docker.io）添加到镜像 引用中。可用镜像和内置智能体工作流请参阅基础镜像。

NOTE

Docker Sandboxes 所使用的 Docker 守护进程直接从镜像仓库拉取模板；它不会共享 宿主机上本地 Docker 守护进程的镜像存储。要把 Docker Hub 的镜像拉取路由到 你组织的镜像仓库基础设施，请配置 镜像仓库镜像加速。

IMPORTANT

对于 Docker Hub，sbx 会复用你的 sbx login 会话来拉取私有镜像。对于其他 镜像仓库（GitHub Container Registry、ECR、ACR、自建 Nexus 等），请在运行 沙箱之前用 sbx secret set --registry 存储拉取凭据：

$ gh auth token | sbx secret set --registry ghcr.io --password-stdin

没有存储凭据时，从非 Docker Hub 镜像仓库的拉取是匿名的，私有镜像会拉取失败。

对于本地构建的镜像，请把镜像保存为 tar 文件并直接加载到沙箱运行时，而不是从 镜像仓库拉取：

$ docker image save my-org/my-template:v1 -o my-template.tar
$ sbx template load my-template.tar
$ sbx run --template my-org/my-template:v1 claude

sbx template load 会把该 tar 导入沙箱运行时的镜像存储，因此创建沙箱时该镜像 无需能从镜像仓库访问到。

模板缓存

创建沙箱时，sbx 默认会检查镜像仓库中的模板镜像并下载缺失或已更新的层。如果 拉取失败但镜像在本地已有缓存，它可以使用缓存的镜像。缓存的镜像在沙箱创建和删除 之间一直保留，并在你运行 sbx reset 时被清除。

更新智能体

智能体模板中包含一个智能体版本，该版本可能与智能体的最新发行版不同。更新 sbx CLI 或拉取更新后的模板，并不会更新已有沙箱内的智能体。

要更新已安装的智能体，请在沙箱内运行其文档中给出的更新命令，可以在沙箱 shell 中执行，也可以用 sbx exec。重启智能体会话即可使用更新后的版本。该更新在沙箱 停止和启动之间会保留，但在你删除沙箱时会被一并删除。如需在其他沙箱中复用更新 后的智能体，请保存为模板。