在受支持的 sbx 命令上使用 --cloud 标志，即可在 Docker 托管的基础设施上创建和管理 沙箱。云端操作使用云端的 ID、名称、资源和生命周期控制，而不是本地沙箱守护进程。

创建沙箱

云沙箱默认在一小时后过期。到期时，服务会停止可以恢复的沙箱，并删除其余沙箱。 在创建之前，先阅读配置过期时间以选择超时时间和对应行为。

为本地沙箱保存的凭据在云沙箱中不可用。启动智能体之前，请先 配置云凭据。

创建沙箱并连接到它的智能体；如果同名沙箱已经存在，则直接复用：

$ sbx --cloud run claude --name cloud-project

不带 --name 时，交互式运行会列出该智能体已有的沙箱，并提供再创建一个的选项。 传入 --new 可以创建全新的沙箱。烘焙了 kit 模板的启动方式也会创建全新沙箱。

复用沙箱会保留它创建时的设置。恢复运行时，--cpus、--memory、--platform、 --ttl、--env 和 --allow-network 等标志会被拒绝。要用不同设置创建沙箱，请使用 --new。

要创建沙箱但不打开智能体会话，使用 create：

$ sbx --cloud create --name cloud-project claude

该命令会打印云沙箱 ID。按 ID 或名称连接：

$ sbx --cloud attach cloud-project

云沙箱名称长度必须为 2–63 个字符，只能包含 ASCII 字母、数字和连字符，并且首尾都 必须是字母或数字。名称 default 是保留的。本地沙箱名称中允许的句点在云端不被接受。

云端创建不接受工作区路径。例如，sbx --cloud run claude . 会返回错误，因为 . 指的是本地文件系统。

选择资源和平台

不带资源标志时，云沙箱以 2 个 CPU 和 4 GiB 内存启动。用 --cpus 和 --memory 选择 下列配置之一：

规格	CPU 数	内存
micro	1	2 GiB
small	2	4 GiB
medium	4	8 GiB
large	8	16 GiB
xl	16	32 GiB

例如：

$ sbx --cloud create --name cloud-project --cpus 4 --memory 8g claude

如果只指定 CPU 或内存其中之一，CLI 会为另一项资源选择匹配的数值。不受支持的组合会被 拒绝。

用 --platform linux/amd64 或 --platform linux/arm64 选择你的账户支持的架构。 当你打算把沙箱迁移到你的机器时，这一点很重要：架构必须匹配。

不连接即运行

在脚本或没有交互输入的终端中，启动沙箱但不打开智能体会话：

$ sbx --cloud run --detach claude --name cloud-task

带 --name 的分离式运行会复用同名沙箱，并在它已停止时将其启动。如果沙箱不存在， 或者你省略了 --name，它会创建一个沙箱。用 sbx --cloud exec 运行命令，用 sbx --cloud rm --force 做无人值守的清理。交互式智能体会话需要在终端中执行 run 或 attach。

要在交互式 run 或 attach 会话中断开连接并让智能体继续运行，按 Ctrl+\。 用 sbx --cloud attach <sandbox-name> 重新连接。重新连接会加入已有的智能体会话。 在 run 或 attach 中使用 --detach-keys 可以更改断开手势，例如 --detach-keys ctrl-x,ctrl-d。

列出和检查沙箱

单独列出云沙箱，与本地沙箱区分开：

$ sbx --cloud ls

大多数云命令都接受沙箱名称或输出中显示的带 sbx_ 前缀的 ID。

查看沙箱的状态、模板、资源、超时设置和已发布的端口 URL：

$ sbx --cloud inspect cloud-project

使用 --format json 或 --format yaml 获取结构化输出。例如，在脚本中获取已发布的端口 URL：

$ sbx --cloud inspect cloud-project --format json | jq -r '.ports[]? | .url // empty'

运行命令

在云沙箱内运行命令：

$ sbx --cloud exec cloud-project pwd

使用 SSH 连接

配置云端 SSH 访问，然后用你的 SSH 客户端连接：

$ sbx --cloud setup ssh
$ ssh sbx_01abc123@sbx_cloud

请把示例替换为 ssh <sandbox-id>@sbx_cloud，使用 sbx --cloud ls 中带 sbx_ 前缀的 ID。

云端 SSH 会遵循你宿主机配置的上游代理。如果代理拒绝 SSH 连接，请参阅 云端 SSH 代理配置。

传输文件

用 sbx --cloud cp 在客户端机器和云沙箱之间复制文件或目录。请使用绝对的沙箱路径：

$ sbx --cloud cp ./src cloud-project:/home/agent/workspace/src
$ sbx --cloud cp cloud-project:/home/agent/workspace/result.json ./result.json

云端复制不会保留权限位和时间戳。下载程序之后，请自行设置可执行权限。

云端复制也不会保留空目录或符号链接本身。符号链接的处理方式因传输方式而异：

• 以符号链接作为源进行上传时，会自动复制它的目标。
• 上传目录时，除非传入 -L（--follow-link）来复制目标，否则会跳过其中的符号链接。
• 下载指向文件的符号链接时，需要 -L 才能复制它的目标。
• 下载目录时会跳过符号链接，即使加了 -L 也是如此。

复制是一次时间点传输。它不会挂载或同步本地路径。对于源代码管理工作流，你也可以在沙箱 内克隆远程仓库，并把改动推送到远程。在创建需要访问私有仓库的沙箱之前，请先配置 云凭据。云端入门指南展示了一个公共仓库的示例。

暴露端口

通过指定沙箱端口来暴露一个 TCP 服务：

$ sbx --cloud ports cloud-project --publish 8080

该命令返回一个由云控制平面分配的公共 HTTPS URL。云模式接受沙箱端口号，可以带可选的 /tcp 后缀，例如 8080/tcp。宿主机 IP 地址、宿主机端口绑定和其他协议会被拒绝。

列出或移除已暴露的端口：

$ sbx --cloud ports cloud-project
$ sbx --cloud ports cloud-project --unpublish 8080

把暴露出来的 URL 当作公共端点对待。在服务中实施身份验证，并在不再需要时移除该暴露。

配置过期时间

在创建时设置生存时间以及到期时采取的行为：

$ sbx --cloud create --name cloud-project --ttl 2h --on-timeout delete claude

默认生存时间为一小时。如果省略 --on-timeout，服务器会停止可以恢复的沙箱，并删除 其余沙箱。当你需要特定结果时，请显式选择一种行为：

• stop 保留沙箱，以便之后重新启动。这要求支持停止该沙箱。
• restart 停止沙箱并立即启动它。如果你同时指定了 --ttl，它必须至少为一小时。
• delete 删除该沙箱。

基于卷的沙箱必须使用 delete 行为。省略 --ttl 会使用服务器默认值。设置 --ttl 0 是错误，并不能用来关闭过期。

查看或延长过期时间。延长不能把过期时间推迟到创建时间之后 24 小时以上：

$ sbx --cloud ttl cloud-project
$ sbx --cloud ttl +30m cloud-project

已停止的沙箱没有正在运行的生存时间，因此 sbx --cloud ttl 会报告它已停止，而不是显示 过期时间。它的生存时间在沙箱恢复时重新开始。在 --json 输出中，stopped 和 ttl_paused 为 true，过期相关字段仍保留之前的截止时间。在沙箱恢复期间，只有 ttl_paused 为 true。

停止或删除沙箱

停止云沙箱，同时保留它的内存和文件系统：

$ sbx --cloud stop cloud-project

停止请求被接受后，该命令即返回。查看 sbx --cloud ls，确认沙箱已经停止。停止期间 不收取计算费用。

恢复沙箱并连接到它的智能体：

$ sbx --cloud attach cloud-project

你也可以使用 sbx --cloud run claude --name cloud-project，或者运行智能体时省略 --name，在提示时选择该沙箱。在带名称的运行中添加 --detach 可以在不连接的情况下 恢复。

恢复会保留沙箱的 ID 和状态，并开启一段新的生存时间。恢复之后，用 sbx --cloud ttl cloud-project 查看它的过期时间。

如果停止或恢复时提示未找到已有沙箱，该操作可能已对你的账户禁用。

基于卷的沙箱无法停止。要结束一个基于卷的沙箱并保存卷快照，请删除该沙箱。

不再需要沙箱状态时，删除该沙箱：

$ sbx --cloud rm cloud-project

删除操作会请求确认，删除云沙箱，且无法撤销。在脚本中用 --force 跳过提示。

智能体退出时删除沙箱

给交互式 run 传入 --rm，可以在智能体会话结束时删除沙箱：

$ sbx --cloud run --rm claude

该会话的断开手势会被关闭，并且不能把 --rm 与 --detach 组合使用。如果会话在未完成 的情况下结束，例如连接中断，沙箱会被保留，CLI 会打印移除它的命令。

使用持久化卷

云卷仍处于实验阶段，独立于沙箱保存数据。先创建卷，然后在创建沙箱时挂载它：

$ sbx --cloud volume create dependency-cache
$ sbx --cloud create --name cloud-project \
    --volume dependency-cache:/workspace/cache claude

新建卷的根目录归 root 所有。挂载之后修改其属主，让智能体能够写入：

$ sbx --cloud exec cloud-project \
    sudo chown agent:agent /workspace/cache

卷数据在沙箱退出时保存为快照，而不是持续保存。如果多个沙箱同时挂载同一个卷，最后 退出的沙箱会覆盖已保存的快照。

定制云沙箱

保存并复用模板

把正在运行的云沙箱保存为模板，以复用它已配置的文件系统。保存之前，请删除写入沙箱 文件系统的凭据：快照会包含这些文件。托管的云密钥仍保留在密钥存储中。请参阅 为云智能体配置身份验证。

$ sbx --cloud template save cloud-project cloud-template
$ sbx --cloud create --name cloud-copy --template cloud-template

默认情况下，保存模板会捕获磁盘状态，由它创建的沙箱从该文件系统冷启动。如果想从 正在运行的沙箱状态恢复，请在 template save 中添加 --capture-mode all。它会捕获 内存、磁盘和 microVM 检查点，加载耗时也更长。

模板会提供它的 CPU 和内存配置。不要把 --template 与智能体名称、--cpus 或 --memory 组合使用。如果想直接启动 OCI 镜像，请使用 --image-ref 并显式指定 CPU 和内存数值。

导入本地模板

云模板有独立的存储。要在云端使用本地模板，请上传它的 tar 文件，并使用一个在你账户中 唯一的名称：

$ sbx --cloud template load my-template.tar cloud-template \
  --cpus 2 --memory-mib 4096

两个资源标志都是必需的，且必须匹配某个云端规格。 与 template save 一样，template load 默认使用磁盘捕获，也接受 --capture-mode all 来同时捕获内存和检查点状态。上传或保存大模板可能需要几分钟。

用 kits 定制

云沙箱同样支持沙箱 kits 和 --kit mixins。关于定制请参阅 Kits， 关于依赖宿主机的功能请参阅本地与云的差异。改造本地 kit 之前，请先 配置云凭据。

用 --kit-arg 或 --kit-args-file 配合 sbx --cloud create，可以把参数传给通过 --kit 提供的 kits。例如，配置一个声明了 version 参数的 mixin：

$ sbx --cloud create --name cloud-tools claude \
    --kit docker.io/<NAMESPACE>/company-cli:1.0.0 \
    --kit-arg company-cli.version=1.2

请把 kit 引用和参数替换为你自己 kit 文档中的内容。company-cli 前缀通过仓库名 指定 kit。

要从文件加载参数，请传入 --kit-args-file <FILE>，每行一条 name=value 条目，例如 company-cli.version=1.2。用 --kit-arg 传入的值会覆盖文件中的值。

要在文件中声明可复用的云端配置，请参阅 在云端使用环境文件。

加载 MCP 服务器

在把 MCP 服务器加载到云沙箱之前，先 在 Docker Agentic Platform 中连接 MCP 服务器。 使用与你使用 sbx 时相同的 Docker 账户。

用控制台中的名称，把已连接的服务器加载到正在运行的云沙箱：

$ sbx --cloud mcp load <server-name> --sandbox cloud-project

服务器名称由与你的 Docker Agentic Platform 账户关联的 MCP 网关解析。云沙箱不使用 通过 sbx mcp add 注册在本地 MCP 存储中的服务器。

列出已有云沙箱网关所报告的服务器，或检查某个沙箱的网关：

$ sbx --cloud mcp ls
$ sbx --cloud mcp ls cloud-project

账户级列表显示各网关报告的服务器，以及使用它们的沙箱。它不包含未被使用的服务器配置， 也不包含被网关跳过的服务器。沙箱视图则包含被跳过的服务器。

诊断云端访问

检查 CLI、Docker 登录状态、云 API 连通性和账户访问权限：

$ sbx --cloud diagnose

这些检查不需要本地沙箱守护进程。关于本地诊断，请参阅 故障排查。

已知限制

Docker exec 和健康检查

在云沙箱内运行 Docker 时，docker exec 可能访问沙箱 VM 的文件系统，而不是目标容器 的文件系统。这也影响 docker compose exec 和 Docker 健康检查，因为它们使用相同的 执行路径。

命令可能因为找不到应用程序文件、可执行文件或挂载的数据而失败。它们也可能在读取或 写入错误的文件时却显示成功。退出状态成功并不能证明该命令使用的是目标容器的文件系统。

健康检查可能报告错误的结果。依赖 condition: service_healthy 的 Compose 服务，即使 所需服务已在运行，也可能一直处于阻塞状态。

由 docker run 启动的容器主进程使用的是正确的文件系统。在你的工作流支持的情况下， 把设置或就绪检查作为容器的主命令来运行。这样可以避免该命令走受影响的 exec 路径， 但并不能恢复 exec 行为或持续的健康监控。