云沙箱把 AI 智能体运行在 Docker 托管的基础设施上，而不是你的本地机器上。当你需要一个 不依赖宿主机计算资源或虚拟化支持的隔离环境时，可以使用云沙箱。

云沙箱与本地沙箱使用同一个 sbx CLI。添加全局 --cloud 标志，即可把受支持的命令 发送到 Cloud Sandboxes API：

$ sbx --cloud ls

云沙箱和本地沙箱的状态彼此独立，能力也不同。云沙箱不能挂载宿主机工作区，也不能使用 宿主机硬件，它的密钥、网络策略、端口和生命周期都由云端管理。在改造本地工作流之前， 请先阅读本地与云的差异。

前置条件

要使用云沙箱，你需要：

• sbx CLI，版本 0.45.0 或更高
• 有效的 Docker Agentic Platform 订阅

按照注册与计费激活云访问权限并查看计算费用。 然后回到本页，从 CLI 登录并配置你的智能体。

从 CLI 登录

使用你订阅时所用的同一个 Docker 账户登录：

$ sbx login

在 CI 等没有浏览器的环境中，可以使用已订阅账户的 Docker 个人访问令牌（PAT）登录：

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

有关 PAT 的配置步骤，请参阅 CI 与无头环境使用。

检查云连接和账户访问权限：

$ sbx --cloud diagnose

如果检查结果显示你的账户没有访问权限，请按照 检查账户访问权限操作。

入门

为本地沙箱配置的凭据在云沙箱中不可用。启动智能体之前，先为它配置云凭据。 对于 Claude Code，存储一个 Anthropic API 密钥：

$ sbx --cloud secret set anthropic

关于其他智能体和凭据选项，请参阅为云智能体配置身份验证。

云沙箱默认在一小时后过期。到期时，服务会停止可以恢复的沙箱，并删除其余沙箱。 在依赖沙箱保留工作成果之前，请先确认超时行为。参见配置过期时间。

创建一个沙箱但不进入交互会话，本例允许访问 GitHub：

$ sbx --cloud create --name cloud-project --allow-network github.com:443 claude

云沙箱不接受本地工作区路径。在沙箱内部克隆公开的 Welcome to Docker 仓库：

$ sbx --cloud exec cloud-project git clone \
    https://github.com/docker/welcome-to-docker.git /home/agent/workspace/project

连接到智能体：

$ sbx --cloud attach cloud-project

让 Claude 查看 /home/agent/workspace/project，并把这个应用的描述写入 /home/agent/workspace/review.md。文件生成完毕后，按 Ctrl+\ 断开连接，让智能体继续运行。

把结果复制到你的机器上：

$ sbx --cloud cp cloud-project:/home/agent/workspace/review.md ./review.md

读取结果，然后用完后删除沙箱：

$ sbx --cloud rm cloud-project

删除操作会清除仅存储在沙箱中的文件。对于你自己的项目，在克隆私有仓库之前，请参阅 传输文件和为云智能体配置身份验证。

了解更多

• 注册与计费介绍激活流程和计算费用
• 本地与云的差异对比两种执行环境
• 使用云沙箱介绍创建、文件、端口和生命周期
• 为云智能体配置身份验证介绍云特有的密钥、API 密钥和 OAuth
• 管理云网络策略介绍账户级和沙箱级的网络访问
• 迁移沙箱说明本地环境与云环境之间的文件系统传输
• sbx CLI 参考列出命令和选项