说明	在本地与云端之间迁移沙箱
用法	sbx move SANDBOX [flags]

描述

在本地主机与 Docker 托管的 Sandboxes 服务之间迁移沙箱。

迁移会把沙箱的文件系统捕获为容器镜像， 并在目标端用它启动一个新沙箱。正在运行的进程和内存中的状态不会随之迁移。 目标沙箱会获得新的 ID；可以用 --name 为它命名。

两个方向都不会删除源沙箱。迁移到云端会停止本地 沙箱；用 'sbx run --name <name>' 重新启动它。迁移到本地会请求 云端源沙箱停止；如果对方拒绝或未确认停止，迁移只会给出警告而不会失败， 而且迁移返回时停止操作可能仍在进行中。 'sbx --cloud ls' 可以查看它的状态。没有智能体的云端沙箱会保持运行。 已停止的云端源沙箱会保留其 ID 和状态： 'sbx --cloud run <id>' 恢复它，'sbx --cloud rm <id>' 删除它。

迁移失败或被取消时，会尽可能恢复。它会重新启动原本正在运行的本地源沙箱， 并删除自己创建的传输模板。重新启动会再次运行入口点； 你手动启动的进程不会被恢复。如果某个清理步骤失败， 输出会指出残留的内容以及用于恢复 它的命令。

不会随之迁移的内容：

• 工作区绑定挂载和其他主机挂载。迁移到本地的文件 会留在沙箱内镜像的工作目录处；用 'sbx cp' 把它们复制出来。
• 由 sbx 管理的密钥。目标端会选取自己的密钥， 因此你可能需要重新登录。保存在被复制文件中的凭据仍会随之迁移。
• 迁移到本地时，挂在云端沙箱上的持久卷和环境变量。 本地沙箱的环境属于其镜像的一部分，会随之迁移到云端。
• 你在本地添加的网络规则。沙箱 Kit 的网络规则会 随之迁移：迁移到云端时会应用它们，与 'sbx create --cloud' 一样。 如果 Kit 无法解析，迁移会发出警告，并采用账户的云端策略。 迁移到本地则从主机的默认策略开始。生效中的本地 L7（HTTP）规则 会在迁移到云端前提示确认；--force 会跳过提示，但仍保留警告。
• 云端 URL 和主机端口绑定。迁移到云端会用新的云端 URL 重新发布 TCP 端口；云端拒绝的端口会被跳过并给出警告。 迁移到本地会保存已发布的 TCP 端口， 并在沙箱运行时把它们绑定到回环地址。主机端口在重新启动后可能变化； 'sbx ports SANDBOX' 可以查看它们。以显式主机绑定发布的 云端端口会阻止迁移到本地。

规格与磁盘：

• 迁移到云端时，会把记录的 CPU 和内存上限向上取整到某个云端规格。 缺少上限时使用云端默认值并给出警告。超过最大规格的上限 会在捕获任何内容之前中止迁移。迁移到本地则使用本地默认值。
• 迁移到本地时，会在主机的临时目录中暂存下载的层。 复用本地层最多可能额外占用 32 GiB，此外还有本地运行时的镜像存储。 如果复用失败，这些层会被重新下载。 如果暂存空间不足，迁移会回退到导出流。

迁移创建的云端沙箱会过期。默认是服务器的 TTL，通常为 1h： 在账户和沙箱支持的情况下，到期时原地停止，否则删除。 用 --ttl 和 --on-timeout 可以选择； '--on-timeout restart' 会让目标沙箱继续运行而不是过期。 稍后可以用 'sbx --cloud ttl' 延长。

选项

选项	默认值	说明
-f, --force		跳过迁移确认提示
--name		目标沙箱名称（默认：'moved-' 加源名称；目标为云端或本地名称已被占用时会追加一段简短的唯一后缀；显式指定的名称原样使用）
--on-timeout		目标云端沙箱的存活时间（TTL）到期时的处理方式：'stop' 让沙箱原地停止，之后可以再次启动；'restart' 通过先停止再立即启动来保持其运行；'delete' 则删除沙箱。并非每个沙箱都支持 'stop'，如果显式请求的操作被服务器拒绝，迁移会在源沙箱已停止并上传之后失败，因此沙箱会被恢复，但传输已消耗。使用 'restart' 时，指定的 --ttl 至少为 1h。默认：沙箱支持时停止，否则使用服务器默认值（删除）。仅在 --to cloud 时可用
--to		迁移的目标位置：'local'（云端到本地）或 'cloud'（本地到云端）
--ttl		目标云端沙箱的存活时间（15s 到 24h，例如 30m、2h；单位不区分大小写；仅在 --to cloud 时可用；默认：由服务端决定）

全局选项

选项	默认值	说明
--cloud		改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表）
-D, --debug		启用调试日志
--no-input		从不提示；需要应答的命令会直接失败，并给出应当运行的命令

示例

# 把云端沙箱迁移到本地主机
sbx move sbx_abc123 --to local

# 把本地沙箱迁移到云端
sbx move my-sandbox --to cloud

# 为目标沙箱指定自定义名称
sbx move sbx_abc123 --to local --name big-refactor

参见

• sbx — 管理 AI 编程智能体沙箱。