Docker Sandboxes

使用环境文件，把云沙箱的智能体、工具、环境变量和资源限制分享给项目的协作者。 运行 sbx --cloud env 即可在 Docker 托管的基础设施上应用这份配置。

云环境拥有自己的文件系统。它不会挂载或同步你机器上的目录，因此不要在文件中写入 workspace。把项目复制进沙箱或在其中克隆，然后把结果复制回来，或者在删除沙箱之前 推送你的提交。凭据和网络策略也独立于你的本地沙箱配置。宿主机生命周期命令仍然在你 自己的机器上、以你自己的权限运行。

NOTE

sbx env 仍处于实验阶段。命令接口和文件格式可能会发生变化。

准备环境 ​

完成云端前置条件，包括激活云访问权限并用 sbx login 登录。 云端计算会收取相应费用。

本示例使用 Claude Code 来处理一个名为 web-app 的本地项目。创建沙箱之前，先在云密钥 存储中配置一个 Anthropic API 密钥：

console
$ sbx --cloud secret set anthropic

该命令会提示输入密钥。关于其他智能体和身份验证选项，请参阅 为云智能体配置身份验证。为本地沙箱配置的凭据在云端不可用。

如果你希望智能体把改动推送到 GitHub，请在创建沙箱之前配置一个 GitHub 令牌：

console
$ sbx --cloud secret set github --sandbox cloud-web-app

该命令会提示输入令牌。请使用对你的仓库有写权限的令牌。--sandbox 的值必须与环境的 name 一致。云环境在创建时选定凭据：事后添加 GitHub 密钥不会让它对已存在的环境生效。 如果你决定稍后推送，先把工作成果复制出来，再用该密钥重新创建环境。

把下面的内容保存为项目根目录下的 cloud.sbxenv.yaml。你也可以把文件放在别处： 它的位置并不决定云沙箱中哪些文件可用。

yaml
schemaVersion: "1"
name: cloud-web-app
agent: claude

env:
  NODE_ENV: test

sandboxOptions:
  cpus: 2
  memory: 4g

这段配置选定 Claude Code，为沙箱设置 NODE_ENV，并申请 2 个 CPU 和 4 GiB 内存。 资源上限必须匹配某个云端规格。你还可以添加 kits 来安装项目工具。

创建沙箱并添加项目 ​

在项目目录下查看计划，并创建沙箱而不进入交互会话：

console
$ sbx --cloud env plan ./cloud.sbxenv.yaml
$ sbx --cloud env create --ttl 2h --on-timeout delete ./cloud.sbxenv.yaml

计划会显示配置和继承的云凭据。创建时会要求你批准该计划，然后才会应用。本例显式设置 在两小时后删除沙箱，因此请在此之前取回你的工作成果。不带超时标志时，云沙箱在一小时后 过期，服务会停止可以恢复的沙箱并删除其余沙箱。其他选项参见 配置过期时间。

把项目复制到沙箱的工作区：

console
$ sbx --cloud cp . cloud-web-app:/home/agent/workspace/web-app

首次复制时请使用一个尚不存在的目标路径。把目录复制到已存在的目录时，它会被嵌套到源 目录名下。请检查你要上传的文件：cp . 不会遵循 .gitignore，它会包含 .env 等隐藏 文件、Git 历史、依赖和构建产物。对于较大的项目，请准备一个只含待上传文件的干净暂存 目录，改为复制该目录。复制是一次性传输：之后任意一侧的编辑都不会同步。目录上传会跳过 符号链接和空目录，并报告跳过了哪些内容。请在沙箱内部安装依赖，而不是复制本地的依赖 目录。

如果采用 Git 工作流，你也可以改为在沙箱内克隆仓库，并把提交推送到你的远程仓库。 为访问私有仓库请配置云凭据，并用云网络策略 配置项目所需的目标地址。复制会包含本地未提交的工作成果；而克隆特定提交可以为协作者 提供可复现的起点。

自动化初始上传 ​

要在每次创建全新沙箱时都上传项目，请在环境文件中添加一个 postCreate 命令。这样初始 上传就成为设置流程的一部分，可以自动完成。

yaml
lifecycle:
  postCreate:
    - name: Upload project
      command: sbx --cloud cp . "$SBX_SANDBOX_NAME:/home/agent/workspace/web-app"

这里 . 解析为环境文件所在的目录。如果你把文件放在别处，或者从暂存目录上传，请把命令 的 workdir 设为项目目录或暂存目录。文件选择规则与手动复制相同，包括复制被忽略的文件 以及跳过符号链接和空目录。

该命令在沙箱创建之后、run 连接到智能体之前，在你的机器上运行。SBX_SANDBOX_NAME 包含沙箱名称，其中包括任何 --name 覆盖值。重新连接会跳过 postCreate，从而保留 智能体的工作。之后本地的编辑不会自动上传。

有了这段配置，使用 sbx --cloud env run ./cloud.sbxenv.yaml 即可创建沙箱、上传项目 并连接到智能体。今后创建沙箱时就不必再手动上传了。

如果上传失败，沙箱已经创建并仍然可用。你可以检查它并手动完成文件传输，或者先用 sbx --cloud env rm ./cloud.sbxenv.yaml 删除它，再重新创建。

关于生命周期命令和审批机制的更多内容，请参阅 用宿主机命令自动化设置。

与智能体协作 ​

使用同一个环境文件连接到 Claude Code：

console
$ sbx --cloud env run ./cloud.sbxenv.yaml

例如，向智能体提出以下要求：

text
在 /home/agent/workspace/web-app 下工作。从 package.json 中找出测试和 lint 命令，
安装依赖，然后运行这些检查。修复所有失败项，并解释你的改动。修改依赖之前先询问我。

再次使用 run 可以重新连接到已存在的沙箱。如果沙箱不存在，它会创建一个。仅在创建 沙箱时传入 --ttl 和 --on-timeout：连接到已存在的沙箱时，run 会拒绝这些标志。

如果你设置了 entrypoint 或 cmd， 或者在 -- 之后传入参数，run 会启动一个全新会话，而不是重新接入已有的智能体进程。 -- 之后的参数会替换 cmd，并保留 entrypoint。例如：

console
$ sbx --cloud env run ./cloud.sbxenv.yaml -- 'Explain this project'

这类会话不支持断开连接和重新接入。

对于没有启动覆盖项、也没有显式参数的运行，按 Ctrl+\ 断开连接，同时让智能体继续 运行。你也可以在没有智能体会话的情况下运行命令，例如查看复制进来的 Git 项目的工作树 状态：

console
$ sbx --cloud env exec ./cloud.sbxenv.yaml -- \
    git -C /home/agent/workspace/web-app diff --stat

后续使用环境命令时，请保持机器、云端点、Docker 账户以及环境文件路径的顺序一致。 CLI 会在本地记录云沙箱的身份，以便在多次调用之间管理它。

取回工作成果并清理 ​

智能体完成后，把项目复制回一个独立的本地目录，这样你可以在更新原文件之前先审阅：

console
$ sbx --cloud cp cloud-web-app:/home/agent/workspace/web-app ../web-app-result

请使用一个尚不存在的目标路径。

改为推送到 GitHub ​

如果你在创建环境之前已经配置了 GitHub 密钥，就可以改用 Git 而非复制文件来取回改动。 这适用于在沙箱内克隆的仓库，或复制进来且 .git 目录中包含仓库历史的 Git 仓库。 请使用你的令牌能够推送的 HTTPS GitHub 远程仓库。

例如，向智能体提出以下要求：

text
在 /home/agent/workspace/web-app 下查看差异，创建一个名为 cloud-fixes 的分支，
把本次任务的改动提交到该分支，并把该分支推送到 origin。

然后在本地检出目录中获取该分支并切换过去进行审阅：

console
$ git fetch origin
$ git switch --track origin/cloud-fixes

即使沙箱被删除，这些提交仍保留在 GitHub 上。

删除环境 ​

保存好工作成果后，删除该环境：

console
$ sbx --cloud env rm ./cloud.sbxenv.yaml

删除操作会请求审批，并删除该沙箱以及此环境配置的密钥。继承来的凭据（例如之前配置的 Anthropic 密钥）会保留。全局绑定也会保留，除非你传入 --prune-bindings。仅存储在 沙箱中的文件会在删除后丢失。

对于无人值守的命令，配合 create、run 或 rm 使用 --force，即为该次调用批准 计划。没有可交互终端时，使用 run --detach。

改造已有的环境文件 ​

云环境支持智能体、kits、环境变量、CPU 与内存上限、受支持提供商的凭据，以及宿主机 生命周期命令。它们只支持环境文件字段 的一个子集。复用本地文件之前，请先做以下检查。

移除本地设置 ​

删除以下声明：

  • workspace、additionalWorkspaces 以及克隆相关选项
  • ports、registries 和 mcp.servers
  • sandboxOptions.template、profile、pullPolicy、skills、display、 gpu、usb 和 writableEnvFiles

不受支持的设置会在宿主机命令或资源准备运行之前被拒绝。显式传入云端文件路径，避免从 ~/.sbxenv.yaml 加载本地设置。对于服务和集成，请使用云命令来 暴露端口和加载 MCP 服务器。

用宿主机命令自动化设置 ​

生命周期命令把云环境的生命周期与你机器上的工作连接起来。当设置或清理依赖本地文件、 工具或凭据时，它们很有用。把这些步骤写进环境文件，可以让工作流变得可重复，即使它 横跨你的机器和云沙箱。

用 initialize 在创建前准备文件，用 preRemove 在运行 sbx --cloud env rm 时取回 结果。当云服务删除过期沙箱时，preRemove 不会运行；命令失败也不会阻止删除。在删除环境 之前保存好需要保留的工作。

宿主机命令会出现在计划中，并需要审批。关于各阶段时机、工作目录和审批选项，请参阅 生命周期命令。

配置云凭据 ​

计划会显示继承的云凭据。沙箱级作用域的凭据会覆盖账户默认值，而在 secrets 中声明的 凭据会覆盖两者。用 snapshot: true 可以一次性解析宿主机命令或 vault 引用并上传该值。快照不会刷新。不支持动态密钥来源和 自定义凭据提供商。凭据绑定要求云端支持 kit 凭据，并需要明确批准该 kit 的注入域名。

应用变更并恢复中断的创建 ​

对密钥、绑定、kits 或资源上限的更改，都需要重新创建沙箱。更新后的 env 值会应用到 后续会话。重新加入正在运行的智能体时，保持该进程的环境不变。

如果创建过程被中断，请在 23 小时内用相同的命令和相同的声明重试。未解决的请求会阻止 删除。请按照恢复提示操作，并在原始请求被解决之前保留它给出的日志。