sbx move 命令在本地沙箱和云沙箱之间传输文件系统快照。用它从另一环境已捕获的文件 系统继续工作，而不要把它当作正在运行的沙箱的实时迁移。

传输行为

一次迁移会执行以下操作：

1. 把源沙箱的文件系统捕获为模板镜像
2. 把该镜像跨本地与云的边界传输
3. 用该镜像创建目标沙箱

目标沙箱会得到不同的沙箱 ID。源沙箱不会被删除，因此传输完成后两个沙箱的状态彼此独立。 从本地迁往云端时，迁移会在捕获过程中停止本地源沙箱。从云端迁往本地时，迁移会在创建 目标沙箱之后尝试停止云端源沙箱。这是一个尽力而为的操作，因此如果无法停止，云端源沙箱 可能仍在运行。迁移命令可能在停止完成之前就返回。用 sbx --cloud ls 查看它的状态。 没有智能体的云端源沙箱会保持运行。验证目标沙箱之后，再单独删除源沙箱。

IMPORTANT

托管密钥不会从源密钥存储复制过来。智能体通过交互式登录写入沙箱内部的凭据属于普通 文件系统文件，会被包含进快照。迁移沙箱之前，请删除沙箱内部的凭据。

迁移会传输存储在沙箱容器中的文件系统数据。它不会传输：

• 正在运行的进程、内存或打开的套接字
• 本地工作区挂载、绑定挂载或克隆模式的卷
• 源密钥存储中的托管密钥
• 挂在沙箱文件系统之外的其他资源

迁移之后对任一沙箱所做的更改都不会同步。

快照保留源沙箱的平台。目标必须支持相同的平台，因为 sbx move 不在 linux/amd64 和 linux/arm64 之间转换。对于从本地迁往云端的操作，你的云账户必须支持本地沙箱的平台。 对于从云端迁往本地的操作，请用 --platform linux/amd64 或 --platform linux/arm64 创建云沙箱，以匹配你的本地沙箱运行时。CLI 在传输快照之前会检查兼容性。

从本地迁往云端

把本地沙箱迁移到云端：

$ sbx move local-project --to cloud

move 命令跨两个后端，因此不要添加全局 --cloud 标志。不带 --name 时，云端目标会 获得一个自动生成的名称，并带有一个简短的唯一后缀。用 --name 设置确切的目标名称：

$ sbx move local-project --to cloud --name cloud-project

无论迁移到哪个方向，显式指定的名称都必须在目标端可用。如果该名称已被占用，命令会在 确认、源捕获和传输之前报告错误。本地名称按不区分大小写的方式比较。云端名称必须在 源智能体的命名空间内可用。

本地工作区文件挂载在沙箱文件系统之外，不会出现在云端目标中。当源沙箱带有工作区时， CLI 会发出警告并请求确认。--force 标志会跳过提示，但不会包含这些文件。

目标沙箱会使用云网络策略，以及沙箱的 kit（或其内置智能体）的网络规则，与 sbx --cloud create 的行为一致。你在本地添加的网络规则不会传输。如果本地源沙箱有 HTTP 方法或路径限制，CLI 会发出警告并请求确认，因为这些限制在云端不会生效。--force 会跳过提示，但保留警告。

已发布的 TCP 沙箱端口会在云端目标上以云端 URL 发布。被云端拒绝的端口会跳过并给出 警告。宿主机端口号和非 TCP 映射不会传输。

目标沙箱可以使用云密钥存储中已存在的适用凭据。本地密钥存储中的凭据不会传输。

CLI 会把源沙箱记录的 CPU 和内存上限向上取整到受支持的 云端规格。缺少上限时使用云端默认值并给出警告。 上限超过最大云端规格时无法迁移。move 命令没有 --cpus 或 --memory 覆盖选项。 资源规格并不保证与源沙箱相同的性能；在删除源沙箱之前，请检查目标端的工作负载表现。

设置目标过期时间

即使本地源沙箱没有过期时间，云端目标也有。不带 --ttl 时使用服务器默认值，通常是 一小时。当账户和沙箱支持时，迁移会请求在过期时停止该沙箱。否则，它会退回到服务器的 默认超时行为，即删除该沙箱。

迁移需要保留的工作成果时，请显式设置过期时间和行为：

$ sbx move local-project --to cloud --ttl 2h --on-timeout stop

stop 行为会保留状态。如果无法停止，显式请求会失败。使用 --on-timeout delete 可以在过期时删除。

要在目标过期时自动重启，使用 restart：

$ sbx move local-project --to cloud --ttl 4h --on-timeout restart

restart 行为会停止并立即启动目标。如果你指定了 --ttl，它必须至少为一小时。

这些标志只适用于迁往云端的操作。迁移之后，用 sbx --cloud ttl 查看或延长过期时间。

从云端迁往本地

按 ID 或名称把云沙箱迁移到本地运行时：

$ sbx move cloud-project --to local --name local-copy

本地目标以宿主机默认网络策略启动。云端网络规则不会复制回本地运行时。

已发布的 TCP 端口会保存在本地沙箱上，并在其运行时绑定到回环地址。重启之后宿主机端口 号可能改变。运行 sbx ports local-copy 查看绑定情况。

迁移不会创建宿主机工作区。用 sbx cp 把文件从本地沙箱复制到你的宿主机。已附加的云卷 和环境变量不会传输。本地目标使用本地的 CPU 和内存默认值。

这个方向要求机器满足本地沙箱的要求，因为该命令会导入快照并创建本地沙箱。除非你用 sbx --cloud rm 显式删除，云端源沙箱仍然可用。

下载过程中的层复用，除本地运行时的镜像存储外，最多可能需要 32 GiB 的宿主机临时磁盘 空间。

验证结果

迁移之后列出两个后端：

$ sbx ls
$ sbx --cloud ls

在删除源沙箱之前，检查目标沙箱的文件系统，并验证它的凭据、端口、卷和其他环境特有的 资源。对于没有随迁过来的内容，请重新配置。