Cube Sandbox v0.3.0 快照体系实战用 snapshot / clone / rollback 为 AI Agent 构建毫秒级「时光机与分身术」【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox在主流 AI Agent 架构中沙箱扮演着安全运行时的角色——真正执行模型生成的代码与外部工具调用。Cube Sandbox v0.3.0 在 22 位贡献者合入的 82 个 commits 之上完成了一次面向 Agent 高并发、长链路与强化学习RL场景的关键架构升级围绕snapshot/clone/rollback三组 SDK 原语把环境复制和出错恢复从分钟级压缩到毫秒级。本文以 v0.3.0 发布说明为核心骨架结合仓库内 Python SDK 实现、cubecow快照引擎与官方示例完整讲解这套状态管理体系的原理、API 用法与实战落地。1. 版本背景一次面向 Agent 的基础设施升级在展开核心的快照能力之前先看 v0.3.0 在基础设施层面的三项改进详见 v0.3.0 变更日志引擎内核cubecow 增量内存新增专为沙箱卷设计的 cubecow 写时复制CoW快照引擎内存侧引入基于 Linux 内核 soft-dirty 机制的增量内存快照。在连续快照场景下系统不再需要写出全量内存仅持久化上次快照以来变化的脏页单个沙箱的快照创建与恢复时间双双降到毫秒级。开发者生态Go SDK WebUI继 Python SDK 之后Go 开发者获得原生 SDK完整覆盖沙箱与模板生命周期管理同时内置 Web 控制台上线直观呈现节点资源负载与沙箱运行状态。Go SDK 的快照相关能力可在 sdk/go/snapshot.go 中看到CreateSnapshot、ListSnapshots、DeleteSnapshot、Rollback、Clone等完整绑定。部署与运维一键安装脚本迁移到 systemd Docker Compose内置 cgroup v2 等系统级预检与诊断脚本提升了在各类云服务器上的环境自适应能力。这些基建更新中最值得展开的是围绕沙箱核心状态管理的快照、回滚与克隆体系。2. 三大 SDK 原语snapshot / clone / rollbackv0.3.0 引入的三组 SDK 接口构成了完整的沙箱状态管理故事。官方指南 docs/guide/snapshot-rollback-clone.md 用一张表概括了它们的语义差异API作用对象Sandbox ID典型用途sb.create_snapshot()源沙箱自身不变创建检查点或持久化状态sb.clone(nN)从运行中的沙箱派生 N 个新沙箱产生 N 个新 IDAgent 并行 rollout、可复现实验sb.rollback(snap_id)将当前沙箱恢复到快照状态不变撤销失败步骤、从保存点分支2.1 snapshot——把当前状态存档sb.create_snapshot()将运行中沙箱的内存、运行时状态与磁盘整体 dump 到持久化存储形成独立的快照文件。快照的生命周期与源沙箱解耦源沙箱被kill()后快照仍然可用snapshot_id可以直接当作模板template批量启动新沙箱。from cubesandbox import Sandbox with Sandbox.create(templateTEMPLATE_ID) as sb: sb.run_code(open(/tmp/data.txt,w).write(hello)) snap sb.create_snapshot() print(fsnapshot: {snap.snapshot_id})从源码看该方法对应POST /sandboxes/:sandboxID/snapshots见 sandbox.py创建期间沙箱会被短暂暂停返回的SnapshotInfo携带snapshot_id与names字段models.py。还支持可选name参数当存在同名模板时新构建会挂到该模板下而不是新建模板。# 列出快照分页 items, next_token Sandbox.list_snapshots() # 按 sandbox_id 过滤 items, _ Sandbox.list_snapshots(sandbox_idsb.sandbox_id) # 清理快照 Sandbox.delete_snapshot(snapshot.snapshot_id)list_snapshots()返回(list[SnapshotInfo], next_token)把next_token传回即可翻页返回None表示没有更多页后端通过x-next-token响应头返回游标默认页大小 100。值得注意的底层细节快照在服务端以模板形式存储delete_snapshot实际调用的是DELETE /templates/:templateID见 sandbox.py删除源沙箱不会级联删除其快照。2.2 clone——一个沙箱裂变成 N 个一行调用从一个运行中的源沙箱派生出 N 个完全独立的副本。核心特性继承性Inheritance每个副本初始状态与源沙箱完全一致——内存、文件、连接隔离性Isolation副本之间、副本与源沙箱之间物理隔离后续写入互不可见连续性Continuity源沙箱不受影响继续运行。接口内置concurrencyC并发控制与任一失败自动清理策略大规模 fan-out 不会留下孤儿沙箱src Sandbox.create(templateTEMPLATE_ID) src.run_code(open(/tmp/shared.txt,w).write(hello)) clones src.clone(n3) for sb in clones: # 每个 clone 都继承了 src 里写入的文件 out sb.run_code(print(open(/tmp/shared.txt).read())).logs.stdout[0] assert out.strip() hello从源码看clone()内部实际执行三步见 sandbox.pycreate_snapshot()——先捕获当前状态Sandbox.create(templatesnap_id)× N——从该快照创建 N 个沙箱附加共享清理状态——最后一个 clone 被 kill 后自动删除临时快照。并发控制方面concurrency 1时通过concurrent.futures.ThreadPoolExecutor派发实际工作线程数为min(n, concurrency)因此传大于n的并发值是无害的concurrency 1时走顺序路径行为与历史一致且不引入线程开销。失败语义是 all-or-nothing只要有一个创建失败所有已成功创建的 sibling 都会被kill()临时快照由_CloneCleanup进程内引用计数做 best-effort 清理然后才向上抛出异常——调用方拿到的要么是全部 N 个沙箱要么是一个异常绝不会收到残缺的中间态。2.3 rollback——一行回到过去某一刻sb.rollback(snapshot_id)将沙箱原地恢复到指定快照状态文件系统完全重置、sandbox_id保持不变、sb对象继续可用无需重连、无需重建。sb Sandbox.create(templateTEMPLATE_ID) sb.run_code(open(/tmp/v.txt,w).write(v1)) checkpoint sb.create_snapshot() sb.run_code(open(/tmp/v.txt,w).write(v2)) sb.rollback(checkpoint.snapshot_id) after sb.run_code(print(open(/tmp/v.txt).read())).logs.stdout[0] assert after.strip() v1实现细节值得留意sandbox.pyrollback 会重启沙箱进程从快照镜像冷启动此前持有的一切 TCP 连接沙箱内 jupyter-server 与 cube-api 的 keep-alive 连接池都会失效。为避免下一次run_code撞上半关闭的 socketSDK 在 rollback 成功后主动关闭底层 HTTP 客户端并懒重建——调用方无需做任何事sb.rollback(...)之后的sb.run_code(...)直接可用。回滚完成后沙箱仍然可写可以继续执行并再次快照# 在回滚后的分支上继续 sb.run_code(open(/tmp/v.txt,w).write(v3)) new_snap sb.create_snapshot() with Sandbox.create(templatenew_snap.snapshot_id) as forked: out forked.run_code(print(open(/tmp/v.txt).read())).logs.stdout[0] assert out.strip() v33. Agent 为什么需要「时光机」与「分身术」在传统 Web 服务里容器大多无状态启动、服务、销毁。但 AI Agent 不是这个模型——Agent 是养出来的它携带内存中的对话上下文、加载好的模型权重、热起来的缓存和已安装的依赖。由此引出两个最常见的痛点。第一养好的环境怎么复制并发任务多了需要分身团队来了新人也要从头养。从零开始重跑 setup 脚本既慢、也无法精确还原内存上下文。而snapshot clone把半小时 × N变成毫秒 × N每个副本都是真正满级的 Agent 环境。第二环境被搞坏了怎么办Agent 干活难免出错——装错依赖、误删文件、跑出死循环。传统做法是销毁容器、从镜像重建、重新pip install几分钟就没了。rollback把出错恢复从分钟级降到百毫秒级且sandbox_id不变Agent 接着跑。4. 四大真实业务场景场景一Agentic RL 训练 / SWE-Bench 评测痛点需要从同一基线出发跑大量独立实例且每次实验必须可复现。Cube 解法# 准备基线环境 base Sandbox.create(templateTEMPLATE_ID) base.run_code(# 安装依赖、下载数据集 ...) snap base.create_snapshot() # 一键派生 100 个独立实例并发创建 clones Sandbox.create(templatesnap.snapshot_id).clone(n100, concurrency10)价值基线只构建一次后续每次扩容都是毫秒级克隆。场景二并行多策略探索痛点想在同一问题上同时尝试多条解决路径。Cube 解法用clone(nN)把当前状态 fork 成 N 个隔离沙箱各跑各的策略后汇总结果。价值探索吞吐线性扩展且各轮次间实验严格对齐。场景三Agent 试错-重试循环痛点某一步执行到一半失败传统补救是杀掉沙箱从头再来。Cube 解法checkpoint sb.create_snapshot() sb.run_code(# 尝试方案 A ...) if failed: sb.rollback(checkpoint.snapshot_id) # 回到 A 之前的时刻 sb.run_code(# 换一种方案重试 ...)价值无需重建环境省时省资源天然贴合 Agent 的 trial-and-error 模式。场景四长生命周期环境复用痛点配好一套复杂开发环境大量依赖不想每次重复搭建。Cube 解法只做一次快照之后所有新沙箱都从该快照创建。价值冷启动与环境初始化合并为一步。5. 底层原理reflink CoW 的存储模型传统虚拟化中快照是重型的运维操作。Cube Sandbox 的快照系统在存储层全程使用reflink配合写时复制CoW语义实现了高效的快照创建与克隆。v0.3.0 变更日志中对应的核心工作包括#360CubeCoW 写时复制快照引擎、#389soft-dirty 增量内存快照、#388快照恢复时的 VSOCK 连接重置、#400移除快照写路径中不必要的sync_all()调用以降低写延迟。存储模型沙箱运行时磁盘数据以 CoW 模式挂载内存同样通过mmap从快照文件按 CoW 方式映射。沙箱启动后所有只读内存页直接映射到底层快照文件——多个沙箱实例共享同一份物理数据零重复。创建快照对运行中的沙箱取新快照时系统只把上次快照以来的脏页写入新快照文件——没有全量序列化、没有全量写盘。脏页通常比总内存小一个数量级快照 I/O 成本大幅下降端到端延迟随之降低。从快照启动reflink让新实例直接引用快照的元数据块——真正的逻辑复制无全量数据拷贝。文件系统级 reflink 近似 O(1)因此从快照冷启动沙箱极快。仓库中的 cubecow/src/lib.rs 印证了这一架构cubecow 库定义了后端无关的Enginetrait 与两个实现——ReflinkEnginexfs-reflink 后端当前主力和S3Engine跨节点 S3 后端并通过initialize()工厂按配置选择具体后端。其Snapshot结构体暴露了export_uuid、export_status、deletable等跨节点导出字段Volume结构体携带snapshot_count派生计数。增量内存机制可在官方基准脚本 bench_snapshot_dirty.py 中得到实证脚本在沙箱内往/dev/shmtmpfs纯 RAM 脏页写入指定 MB 数后取快照再从 vmm.log 中 grep 匹配PagemapAnon snapshot saved首次全量或Soft-dirty snapshot saved后续增量日志来核对实际写入字节数验证只写脏页的语义。建议用法是多次调用并扫描脏页尺寸例如python bench_snapshot_dirty.py -d 0、-d 10、-d 100、-d 1024。在这套存储原语之上SDK 把clone与rollback封装成简单的一行调用6. 上手实践安装与两个完整示例安装与环境变量注意snapshot、rollback、clone 是 Cube Sandbox 独占能力——e2b SDK 没有对等 API。cubesandboxSDK 与 e2b SDK 兼容可作 drop-in 替换同时新增这些高级特性协议层面 Cube Sandbox 深度兼容 E2B。本指南所有 API 需要cubesandbox0.2.0 或更高版本pip install cubesandbox0.2.0示例中使用的环境变量export CUBE_API_URLhttp://127.0.0.1:3000 export CUBE_TEMPLATE_IDtpl-xxxxxxxxxxxxxxxxxxxxxxxx仓库在 examples/snapshot-rollback-clone/ 提供了可直接运行的完整 demo 套件包括01_create_snapshot.py、02_list_snapshots.py、03_clone_from_snapshot.py、05_snapshot_outlives_sandbox.py、11_delete_snapshot.py以及bench_snapshot_concurrency.py/bench_snapshot_dirty.py两个基准脚本。其中05_snapshot_outlives_sandbox.py专门演示快照在源沙箱销毁后仍可用的生命周期解耦语义。示例一错误隔离与原地回滚在沙箱生命周期的任何有意义节点放下检查点。无论之后环境被破坏得多严重一行sb.rollback(checkpoint_id)就能恢复到那一刻——关键是sandbox_id与沙箱对象保持不变可以继续使用from cubesandbox import Sandbox from env import TEMPLATE_ID # Step 1: 在 v0 状态取一个基础快照 with Sandbox.create(templateTEMPLATE_ID) as src: src.run_code(open(/tmp/v.txt, w).write(v0)) base src.create_snapshot() base_id base.snapshot_id print(fbase snapshot (v0): {base_id}) # Step 2: 从基础快照派生一个新沙箱 sb Sandbox.create(templatebase_id) print(fderived sandbox: {sb.sandbox_id}) # Step 3: 写入 v1 并放下检查点 sb.run_code(open(/tmp/v.txt, w).write(v1)) checkpoint sb.create_snapshot() checkpoint_id checkpoint.snapshot_id print(fcheckpoint (v1): {checkpoint_id}) # Step 4: 写入 v2 并确认落盘 sb.run_code(open(/tmp/v.txt, w).write(v2)) before sb.run_code(print(open(/tmp/v.txt).read())).logs.stdout before before[0].strip() if before else print(fbefore rollback: {before!r}) assert before v2 # Step 5: 回滚到 v1 检查点 sb.rollback(checkpoint_id) print(frolled back to checkpoint {checkpoint_id}) # Step 6: 验证状态恢复到 v1sandbox_id 不变 after sb.run_code(print(open(/tmp/v.txt).read())).logs.stdout after after[0].strip() if after else print(fafter rollback: {after!r}) assert after v1, fexpected v1, got {after!r} print(OK: rollback restored state to checkpoint (v1)) # Cleanup sb.kill() Sandbox.delete_snapshot(checkpoint_id) Sandbox.delete_snapshot(base_id) print(snapshots deleted)示例二并行探索的高效克隆在强化学习或多路径决策中clone可以一次调用从单个源沙箱派生出许多环境——每个副本物理隔离却完整继承源沙箱的运行时状态。下面示例克隆 N 个副本并逐一验证每个副本都继承了源沙箱中写入的标记文件import os from cubesandbox import Sandbox from env import TEMPLATE_ID N int(os.environ.get(FORK_N, 10)) CONCURRENCY int(os.environ.get(FORK_CONCURRENCY, 5)) src Sandbox.create(templateTEMPLATE_ID) src.run_code(open(/tmp/origin.txt, w).write(I am from sandbox a)) print(fsrc sandbox: {src.sandbox_id}) # ★ 并发克隆——SDK 在内部 fan-out Sandbox.create clones src.clone(nN, concurrencyCONCURRENCY) print(fcloned {len(clones)} sandboxes (concurrency{CONCURRENCY})) # 验证每个 clone 都继承了源的状态标记 expect I am from sandbox a ok 0 for i, sb in enumerate(clones): r sb.run_code(print(open(/tmp/origin.txt).read())) marker r.logs.stdout[0].strip() if r.logs.stdout else if marker expect: ok 1 print(f clone[{i:2}] {sb.sandbox_id} marker{marker!r}) print(f\n{ok}/{N} clones inherited the origin marker) assert ok N, some clones failed to inherit state # Cleanup src.kill() for sb in clones: sb.kill() print(all sandboxes killed)由于 Cube Sandbox 在协议层面深度兼容 E2B而这些原语在 E2B 原生 API 中并不存在Cube 团队通过cubesandboxSDK 在应用层补齐了它们——开发者无需改动现有 E2B 兼容代码即可解锁这些高级状态管理能力。7. 最佳实践与资源清理官方指南给出了四条重要经验docs/guide/snapshot-rollback-clone.md快照不是免费的。每个快照对应持久化存储中的一份完整镜像。不再需要时应删除快照或周期性运行list_snapshots()做清理。with块不会删除快照。上下文管理器只调用kill()沙箱。create_snapshot()创建的快照必须显式调用Sandbox.delete_snapshot()清理。clone()自动清理内部快照。临时 fan-out 场景无需自己管理快照生命周期直接调用clone()即可——正如 2.2 节源码所示临时快照由进程内_CloneCleanup在最后一个 clone 被 kill 后自动删除。大规模 fan-out 优先clone(nN, concurrencyC)。SDK 在失败时负责清理避免孤儿资源。8. 延伸跨节点快照Pause / Resume / FromSnapv0.3.0 之后的版本将快照体系进一步扩展到集群维度完整说明见 docs/guide/cross-node-snapshot.md。其核心思路CubeSandbox 把沙箱持久化为rootfs / memory / metadata三件套。默认xfs后端下包停留在创建节点Resume 与 FromSnap 必须回到该节点而启用s3后端由 CubeS3lvol 管理后快照包会上传到集群共享 S3任何兼容节点都可按需拉取从而实现跨节点恢复。跨节点恢复需要同时满足模板在创建时声明--backend s3后端选择一旦锁定不可中途切换且沿 template → sandbox → snapshot 链条继承快照的remote_status达到ready状态机为pending → inprogress → ready / failed只有ready解锁跨节点恢复目标节点与源节点的cpuid_hash与host_kernel_release相等且目标节点kvm_module_taint为空调度器restoreplace始终优先源节点仅当源节点不可调度时才尝试跨节点。9. 配套的 Web 控制台Preview除 SDK 级snapshot/rollback/cloneAPI 外v0.3.0 还开源了一个基于 Cube Sandbox 的 AgentHub 数字助手控制台预览版变更日志中对应#420每个沙箱的实时快照时间线、一键回滚到任意检查点、按需 fan-out 多个并行探索环境、批量生命周期管理全部变成浏览器里的点按操作。原本需要对着 SDK 写脚本的时光机和分身术现在只需几次点击。10. 后续规划v0.3.0 发布说明预告了下一阶段的沙箱安全升级方向是从隔离 Agent 运行在哪里推进到控制 Agent 能触碰什么内置内容感知的网络控制与审计在沙箱网络边界提供内容感知的出站访问控制与完整审计轨迹让Agent 调用了哪个外部 API、发出了什么数据全程可追踪、可拦截凭据保险库Credential VaultAPI Key、数据库密码、云凭据在沙箱安全侧集中管理Agent 只能看到有作用域、临时的凭据让密钥远离模型上下文与日志。参考快照、回滚与克隆官方指南跨节点快照Pause / Resume / FromSnapv0.3.0 变更日志Python SDK 实现create_snapshot / clone / rollbackGo SDK 快照绑定cubecow 存储引擎官方示例与基准脚本【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考