# 沙箱快照
<subtitle>从正在运行的沙箱创建可复用的时间点快照，并用它启动新的沙箱。</subtitle>

沙箱快照可以捕获某一时刻正在运行的沙箱状态，包括文件系统和内存状态。之后，您可以使用这个快照创建新的沙箱，新沙箱会从快照记录的状态开始运行。

创建快照后，原沙箱会继续运行。一个快照可以反复用于创建多个新沙箱，适合做检查点、回滚点或可复用的运行时环境。

> 沙箱快照会占用持久化存储，并按持久化存储规则计费。详细计费方式请参考 [计费说明](/docs/agent-sandbox/product/fee.md)。

## 使用前说明

如果您基于较早创建的自定义模板启动沙箱，创建快照时遇到运行时版本或模板兼容问题，请先重新构建模板，再重新创建沙箱并执行快照操作。

## 快照与暂停恢复

| | 暂停/恢复 | 快照 |
| --- | --- | --- |
| 对原沙箱的影响 | 暂停原沙箱 | 原沙箱会短暂暂停，随后继续运行 |
| 关系 | 一对一：恢复的是同一个沙箱 | 一对多：一个快照可以创建多个新沙箱 |
| 适用场景 | 挂起并稍后恢复单个沙箱 | 创建可复用的检查点 |

如需暂停并恢复同一个沙箱，请参考 [沙箱持久化](/docs/agent-sandbox/sdk/sandbox/persistence.md)。

## 快照流程

```mermaid actions={false}
graph LR
    A[运行中的沙箱] -->|createSnapshot| B[创建快照中]
    B --> C[快照已创建]
    B --> A
    C -->|Sandbox.create| D[新沙箱 1]
    C -->|Sandbox.create| E[新沙箱 2]
    C -->|Sandbox.create| F[新沙箱 N]
```

创建快照时，沙箱会短暂暂停，完成后会自动回到运行状态。快照完成后，原沙箱 ID 保持不变。

> 创建快照期间，沙箱会经历短暂的暂停和恢复。这会导致活跃连接断开，例如 WebSocket、PTY、命令流等。请确保客户端具备重连能力。

## 创建快照

您可以从正在运行的沙箱实例创建快照。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

# 从正在运行的沙箱创建快照
snapshot = sandbox.create_snapshot()
print("Snapshot ID:", snapshot.snapshot_id)
```

也可以通过沙箱 ID 调用静态方法创建快照。

```python
from ucloud_sandbox import Sandbox

sandbox_id = "your-sandbox-id"

# 通过沙箱 ID 创建快照
snapshot = Sandbox.create_snapshot(sandbox_id)
print("Snapshot ID:", snapshot.snapshot_id)
```

## 从快照创建沙箱

快照 ID 可以直接传给 `Sandbox.create()`，用于创建一个从快照状态启动的新沙箱。新沙箱会带有快照捕获时的文件系统和内存状态。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
snapshot = sandbox.create_snapshot()

# 从快照创建新沙箱
new_sandbox = Sandbox.create(snapshot.snapshot_id)
print("New sandbox ID:", new_sandbox.sandbox_id)
```

## 列出快照

您可以列出当前账号下的所有快照。该方法返回分页器，适合遍历较多结果。

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list_snapshots()

snapshots = []
while paginator.has_next:
    items = paginator.next_items()
    snapshots.extend(items)

for snapshot in snapshots:
    print(snapshot.snapshot_id)
```

### 按沙箱过滤

您也可以只查询某个沙箱创建出来的快照。

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list_snapshots(sandbox_id="your-sandbox-id")
snapshots = paginator.next_items()

for snapshot in snapshots:
    print(snapshot.snapshot_id)
```

## 删除快照

不再需要的快照应及时删除，以释放持久化存储。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
snapshot = sandbox.create_snapshot()

Sandbox.delete_snapshot(snapshot.snapshot_id)
```

## 快照与模板

快照和 [模板](/docs/agent-sandbox/template/01-quick-start.md) 都可以作为创建沙箱的起点，但它们解决的问题不同。

| | 模板 | 快照 |
| --- | --- | --- |
| 定义方式 | 通过声明式代码定义环境 | 捕获正在运行的沙箱 |
| 可复现性 | 相同定义会构建出一致的基础环境 | 捕获某一时刻已经发生的运行时状态 |
| 适合场景 | 标准化、可重复的基础环境 | 检查点、回滚、分叉运行状态 |

当您希望每个沙箱都从相同、已知、可重复的基础环境开始时，应使用模板，例如预装工具、固定配置和一致的依赖环境。

当您需要捕获或分叉一个已经运行过的实时状态时，应使用快照，例如任务执行到一半、内存中已有中间结果、服务已经启动完成等。

## 典型场景

- **保存 Agent 工作检查点**：AI Agent 已加载数据并在内存中产生中间结果，可以创建快照，之后从该状态继续或分叉。
- **创建回滚点**：在执行高风险或高成本操作前创建快照，例如运行不可信代码、执行迁移、重构应用；如果失败，可以从快照创建新沙箱回到操作前状态。
- **分叉工作流**：从同一个快照创建多个沙箱，并行尝试不同方案。
- **缓存运行时环境**：对已经完成昂贵初始化的沙箱创建快照，避免后续重复安装依赖、加载大数据集或启动长进程。
- **共享运行状态**：一个用户或 Agent 配置好环境后创建快照，其他用户或 Agent 可以从完全相同的状态开始。