生命周期与状态管理

CubeSandbox 的一个核心优势是：它不只会“启动一个隔离环境”，还会管理这个环境的状态。对 Agent 来说，状态往往就是价值，例如已经安装好的依赖、打开的浏览器会话、调试到一半的代码仓库。

基础状态模型

状态	含义
running	沙箱正在运行，占用 CPU/内存，可以执行代码或接收请求。
pausing	平台正在保存状态，瞬时态。
paused	沙箱已暂停，CPU/内存释放，状态保存在快照中。
resuming	平台正在从快照恢复，瞬时态。
terminated	沙箱已销毁，不能恢复。

timeout 与 on_timeout

创建沙箱时，最重要的两个生命周期参数是：

参数	作用
timeout	空闲多久后触发超时，单位通常按 Cube SDK 语义为秒。
lifecycle.on_timeout	超时后是 kill 还是 pause。

默认语义通常偏向自动销毁，避免忘记释放资源。如果你希望保留状态，显式配置 on_timeout="pause"。

自动暂停和自动恢复

典型 Agent 交互并不是持续占用沙箱：用户输入、模型思考、沙箱执行、等待下一轮。等待期间可以自动暂停：

from cubesandbox import Sandbox

sandbox = Sandbox.create(
    template="<template-id>",
    timeout=300,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

行为：

• 空闲超过 timeout 后，平台保存状态并释放资源。
• 下一次请求到达时，CubeProxy sidecar 触发自动恢复。
• 恢复后重新获得一个新的 timeout 窗口。

适合场景：

• 交互式代码解释器。
• 浏览器自动化任务等待下一轮指令。
• 长对话 Agent 的临时开发环境。

不适合场景：

• 必须保持外部 TCP 连接不断开的服务。
• 明确只需要一次性执行的短任务。
• 对恢复延迟极端敏感且资源充足的常驻服务。

显式暂停与恢复

如果你想自己控制节奏，可以显式调用：

sb.pause()
sb.connect()

显式暂停适合“我确定这段时间不用，但还要回来”的场景。显式销毁则使用：

sb.kill()

kill() 是不可逆操作；它表示这个沙箱不再需要。

快照

快照是一个可复用 checkpoint：

from cubesandbox import Sandbox

with Sandbox.create(template="<template-id>") as sb:
    sb.run_code("open('/tmp/state.txt', 'w').write('v1')")
    snap = sb.create_snapshot()
    print(snap.snapshot_id)

快照独立于源沙箱。源沙箱销毁后，快照仍可用于创建新沙箱或回滚。

克隆

克隆用于从当前状态派生多个独立副本：

src = Sandbox.create(template="<template-id>")
src.run_code("open('/tmp/shared.txt', 'w').write('base')")

clones = src.clone(n=3, concurrency=3)

适合：

• Agent 并行尝试多种修复方案。
• 多模型比较同一初始状态。
• 训练或评测任务 fan-out。

克隆出来的副本初始状态相同，后续写入互不影响。

回滚

回滚把同一个沙箱恢复到旧状态，沙箱 ID 不变：

sb.run_code("open('/tmp/value.txt', 'w').write('before')")
snap = sb.create_snapshot()

sb.run_code("open('/tmp/value.txt', 'w').write('after')")
sb.rollback(snap.snapshot_id)

适合：

• Agent 执行失败后回到安全点重试。
• 教学环境“一键还原”。
• 浏览器或服务状态恢复。

使用建议

场景	推荐能力
一次性代码执行	timeout + 默认销毁。
交互式会话	on_timeout="pause" + auto_resume=True。
多分支探索	create_snapshot() + clone()。
失败可恢复任务	每个关键步骤前 create_snapshot()，失败后 rollback()。
长期服务托管	较长 timeout，谨慎启用自动暂停，应用层处理重连。

下一步

继续阅读 网络与安全，学习如何限制沙箱出网并托管密钥。