CubeSandbox沙箱生命周期状态机全解从create到destroy的完整旅程【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是一个专为 AI Agent 打造的即时、并发、安全且轻量的沙箱平台。理解 CubeSandbox 沙箱生命周期状态机是掌握它从create到destroy完整旅程的第一步每个沙箱始终处于running、pausing、paused、resuming、terminated这 5 种状态之一由timeout、on_timeout、auto_resume三个开关驱动流转。本文带你一次看懂这套状态机。状态机全览5个状态一次看懂CubeSandbox 中沙箱是核心运行时单元任意时刻只处于以下 5 个状态之一状态含义是否消耗 CPU/内存running活跃运行中可接受请求、执行代码✅ 是pausing平台正在对 VM 打快照瞬时过渡态正在释放paused快照已落盘零CPU/内存成本完整状态保留❌ 否resuming平台正在从快照恢复瞬时过渡态正在重建terminated被kill()或超时回收不可恢复❌ 否其中pausing和resuming只是短暂过渡你几乎看不到它们真正需要理解的是三条主干路径活跃路径running↔paused由 connect / 自动恢复触发终结路径任意状态 →terminatedkill()永远优先时间路径空闲超时 → 根据on_timeout走向paused或terminated 直觉记忆pause 是存档kill 是删档。第一步Create —— 从模板到 running沙箱由模板启动。调用Sandbox.create()后平台完成调度、资源分配与 VM 启动状态进入running。创建时你只需关心几个关键参数参数作用template启动所用模板 IDtimeout空闲多少秒后触发超时省略则由集群默认值决定lifecycle生命周期策略on_timeout/auto_resumemetadata/env_vars自定义键值对 / 注入的环境变量timeout的取值有讲究-1NEVER_TIMEOUT表示永不超时0表示首次空闲扫描即回收正整数 N 表示空闲 N 秒后触发。创建成功后get_info()会返回startedAt与endAt——后者就是按当前timeout预测的下次超时时刻每次有请求到达都会刷新。第二步Pause —— 把运行态存档到零成本调用pause()或空闲超时且on_timeoutpause后沙箱进入pausing平台将 VM 的 CPU 寄存器、进程内存、TCP 状态与文件系统变更全部冻结进快照完成后状态变为pausedCPU 和内存被物理回收成本归零而进程状态完整保留。快照存储在底层走的是 CoW写时复制 reflink 的极速路径——paused状态不占计算资源只占存储。⚠️ 注意手动pause()不会取消空闲回收。默认on_timeoutkill下已暂停的沙箱若空闲超过timeout仍会被销毁。想让暂停的沙箱长期存活请传timeoutNEVER_TIMEOUT。第三步Resume —— 无感唤醒回 running从paused回到running有两条路显式恢复调用sandbox.connect()快照被还原继续执行时如同从未暂停过自动恢复创建时设置lifecycle{on_timeout: pause, auto_resume: True}之后任何请求HTTP、run_code、文件 I/O到达一个paused沙箱时平台会在请求落地前先把它唤醒——调用方完全无感典型恢复延迟在亚秒到数秒级。每次自动恢复都会重置空闲时钟超时时长不变因此恢复 → 短用 → 空闲 → 再暂停的循环可以无限重复。这正是 Agent 工作负载的理想形态用户输入 → 模型思考 → 沙箱执行 → 空闲时被自动暂停省资源。另有两个细节值得了解恢复会重建 guest 网卡与主机端口并重写代理路由CubeProxy 的本地缓存会被同步清理避免流量仍指向暂停前的旧 IP若节点资源不足resume 可能被准入检查拒绝HTTP 409可重试——这由节点级配置paused_resource_release_ratio控制0表示暂停沙箱始终保留配额恢复永不失败1表示配额完全释放最大化密度。第四步Terminate —— kill 与 destroy 的终局terminated是唯一的终点不可逆显式kill()无论沙箱处于running还是paused无论是否配置了on_timeoutpausekill()都优先生效并丢弃快照超时回收on_timeoutkill默认时空闲超过timeout即被销毁下一个请求会得到410 GoneSDK 客户端应停止重试删除 paused 沙箱DELETE接口会直接移除暂停墓碑、删除暂停快照并清理控制面元数据——它不会先恢复 MicroVM也无需节点容量准入清理完成后同步返回204 No Content。幕后机制CubeMaster 与 CLM 如何协同状态机的手脚由两个组件分工完成源码可查组件职责CubeMaster控制面单写者成功 pause/resume 后向 Redis Stream 广播state事件只广播paused/running两个终态元数据快照存于lifecycle:metacube-lifecycle-managerCLM自动暂停/恢复协调者消费事件流持有每沙箱状态键running/pausing/paused/resuming/killing/killed负责空闲扫描sweeper与自动唤醒resumer协调上有几个精巧设计事件流 快照双通道CLM 多副本各自消费 append-only 事件流启动时从元数据快照引导保证每个热备副本都持有完整注册表过渡锁语义pausing/resuming等过渡标记只存在于 CLM 的 per-sandbox 状态键中通过SETNX过渡锁保证同一沙箱的 pause/resume 串行执行多副本不会打架领导选举Kubernetes 部署默认 2 个热备副本Redis 租约选出唯一执行者做空闲扫描与清理副本故障切换后最多多做一次 pause/resume下个请求照常自动恢复。关键源码位置事件与状态定义CubeMaster/pkg/lifecycle/schema.goRedis 写入实现CubeMaster/pkg/lifecycle/store.go状态键协调CLM 侧镜像cube-lifecycle-manager/internal/lifecycle/schema.go一条完整的旅程串起来把上面所有内容连成一条 Agent 沙箱的典型旅程create(timeout300, lifecycle{on_timeout:pause, auto_resume:True})→ 沙箱进入running执行完一段代码后空闲 5 分钟 → CLM 空闲扫描触发自动暂停running → pausing → pausedCPU/内存归零用户下一轮对话的请求到来 → CubeProxy 回调 CLM 的/internal/resumepaused → resuming → running请求无感落地空闲时钟重置如此循环 N 轮……用户最终kill()或会话结束 →terminated快照与资源全部释放。延伸阅读官方生命周期指南含完整 SDK 示例docs/guide/lifecycle.md跨节点快照恢复docs/guide/cross-node-snapshot.md快照/克隆/回滚深入剖析docs/guide/snapshot-rollback-clone.md端到端演示脚本examples/code-sandbox-quickstart/auto-resume.py、examples/code-sandbox-quickstart/auto-kill.py软删除与清理策略docs/guide/soft-delete-purge.md掌握这套状态机后你会发现CubeSandbox 的设计哲学非常清晰——让沙箱像游戏存档一样随时暂停、随时续玩、随时删档而 AI Agent 永远感受不到背后那台 MicroVM 的沉睡与苏醒。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CubeSandbox沙箱生命周期状态机全解：从create到destroy的完整旅程
CubeSandbox沙箱生命周期状态机全解从create到destroy的完整旅程【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是一个专为 AI Agent 打造的即时、并发、安全且轻量的沙箱平台。理解 CubeSandbox 沙箱生命周期状态机是掌握它从create到destroy完整旅程的第一步每个沙箱始终处于running、pausing、paused、resuming、terminated这 5 种状态之一由timeout、on_timeout、auto_resume三个开关驱动流转。本文带你一次看懂这套状态机。状态机全览5个状态一次看懂CubeSandbox 中沙箱是核心运行时单元任意时刻只处于以下 5 个状态之一状态含义是否消耗 CPU/内存running活跃运行中可接受请求、执行代码✅ 是pausing平台正在对 VM 打快照瞬时过渡态正在释放paused快照已落盘零CPU/内存成本完整状态保留❌ 否resuming平台正在从快照恢复瞬时过渡态正在重建terminated被kill()或超时回收不可恢复❌ 否其中pausing和resuming只是短暂过渡你几乎看不到它们真正需要理解的是三条主干路径活跃路径running↔paused由 connect / 自动恢复触发终结路径任意状态 →terminatedkill()永远优先时间路径空闲超时 → 根据on_timeout走向paused或terminated 直觉记忆pause 是存档kill 是删档。第一步Create —— 从模板到 running沙箱由模板启动。调用Sandbox.create()后平台完成调度、资源分配与 VM 启动状态进入running。创建时你只需关心几个关键参数参数作用template启动所用模板 IDtimeout空闲多少秒后触发超时省略则由集群默认值决定lifecycle生命周期策略on_timeout/auto_resumemetadata/env_vars自定义键值对 / 注入的环境变量timeout的取值有讲究-1NEVER_TIMEOUT表示永不超时0表示首次空闲扫描即回收正整数 N 表示空闲 N 秒后触发。创建成功后get_info()会返回startedAt与endAt——后者就是按当前timeout预测的下次超时时刻每次有请求到达都会刷新。第二步Pause —— 把运行态存档到零成本调用pause()或空闲超时且on_timeoutpause后沙箱进入pausing平台将 VM 的 CPU 寄存器、进程内存、TCP 状态与文件系统变更全部冻结进快照完成后状态变为pausedCPU 和内存被物理回收成本归零而进程状态完整保留。快照存储在底层走的是 CoW写时复制 reflink 的极速路径——paused状态不占计算资源只占存储。⚠️ 注意手动pause()不会取消空闲回收。默认on_timeoutkill下已暂停的沙箱若空闲超过timeout仍会被销毁。想让暂停的沙箱长期存活请传timeoutNEVER_TIMEOUT。第三步Resume —— 无感唤醒回 running从paused回到running有两条路显式恢复调用sandbox.connect()快照被还原继续执行时如同从未暂停过自动恢复创建时设置lifecycle{on_timeout: pause, auto_resume: True}之后任何请求HTTP、run_code、文件 I/O到达一个paused沙箱时平台会在请求落地前先把它唤醒——调用方完全无感典型恢复延迟在亚秒到数秒级。每次自动恢复都会重置空闲时钟超时时长不变因此恢复 → 短用 → 空闲 → 再暂停的循环可以无限重复。这正是 Agent 工作负载的理想形态用户输入 → 模型思考 → 沙箱执行 → 空闲时被自动暂停省资源。另有两个细节值得了解恢复会重建 guest 网卡与主机端口并重写代理路由CubeProxy 的本地缓存会被同步清理避免流量仍指向暂停前的旧 IP若节点资源不足resume 可能被准入检查拒绝HTTP 409可重试——这由节点级配置paused_resource_release_ratio控制0表示暂停沙箱始终保留配额恢复永不失败1表示配额完全释放最大化密度。第四步Terminate —— kill 与 destroy 的终局terminated是唯一的终点不可逆显式kill()无论沙箱处于running还是paused无论是否配置了on_timeoutpausekill()都优先生效并丢弃快照超时回收on_timeoutkill默认时空闲超过timeout即被销毁下一个请求会得到410 GoneSDK 客户端应停止重试删除 paused 沙箱DELETE接口会直接移除暂停墓碑、删除暂停快照并清理控制面元数据——它不会先恢复 MicroVM也无需节点容量准入清理完成后同步返回204 No Content。幕后机制CubeMaster 与 CLM 如何协同状态机的手脚由两个组件分工完成源码可查组件职责CubeMaster控制面单写者成功 pause/resume 后向 Redis Stream 广播state事件只广播paused/running两个终态元数据快照存于lifecycle:metacube-lifecycle-managerCLM自动暂停/恢复协调者消费事件流持有每沙箱状态键running/pausing/paused/resuming/killing/killed负责空闲扫描sweeper与自动唤醒resumer协调上有几个精巧设计事件流 快照双通道CLM 多副本各自消费 append-only 事件流启动时从元数据快照引导保证每个热备副本都持有完整注册表过渡锁语义pausing/resuming等过渡标记只存在于 CLM 的 per-sandbox 状态键中通过SETNX过渡锁保证同一沙箱的 pause/resume 串行执行多副本不会打架领导选举Kubernetes 部署默认 2 个热备副本Redis 租约选出唯一执行者做空闲扫描与清理副本故障切换后最多多做一次 pause/resume下个请求照常自动恢复。关键源码位置事件与状态定义CubeMaster/pkg/lifecycle/schema.goRedis 写入实现CubeMaster/pkg/lifecycle/store.go状态键协调CLM 侧镜像cube-lifecycle-manager/internal/lifecycle/schema.go一条完整的旅程串起来把上面所有内容连成一条 Agent 沙箱的典型旅程create(timeout300, lifecycle{on_timeout:pause, auto_resume:True})→ 沙箱进入running执行完一段代码后空闲 5 分钟 → CLM 空闲扫描触发自动暂停running → pausing → pausedCPU/内存归零用户下一轮对话的请求到来 → CubeProxy 回调 CLM 的/internal/resumepaused → resuming → running请求无感落地空闲时钟重置如此循环 N 轮……用户最终kill()或会话结束 →terminated快照与资源全部释放。延伸阅读官方生命周期指南含完整 SDK 示例docs/guide/lifecycle.md跨节点快照恢复docs/guide/cross-node-snapshot.md快照/克隆/回滚深入剖析docs/guide/snapshot-rollback-clone.md端到端演示脚本examples/code-sandbox-quickstart/auto-resume.py、examples/code-sandbox-quickstart/auto-kill.py软删除与清理策略docs/guide/soft-delete-purge.md掌握这套状态机后你会发现CubeSandbox 的设计哲学非常清晰——让沙箱像游戏存档一样随时暂停、随时续玩、随时删档而 AI Agent 永远感受不到背后那台 MicroVM 的沉睡与苏醒。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考