# Sandbox snapshot
<subtitle>Create a reusable point-in-time snapshot from a running sandbox and use it to launch a new sandbox. </subtitle>

Sandbox snapshots can capture the status of the running sandbox at a certain moment, including file system and memory status. You can then use this snapshot to create a new sandbox, which will run from the state recorded by the snapshot.

After the snapshot is created, the original sandbox will continue to run. A snapshot can be used repeatedly to create multiple new sandboxes, suitable for checkpoints, rollback points, or reusable runtime environments.

> Sandbox snapshots will occupy persistent storage and are billed according to persistent storage rules. For detailed billing methods, please refer to [Billing Instructions](/docs/agent-sandbox/product/fee.md).

## Instructions before use

If you start the sandbox based on a custom template created earlier and encounter runtime version or template compatibility issues when creating a snapshot, please rebuild the template first, then re-create the sandbox and perform the snapshot operation.

## Snapshot and pause recovery

| | Pause/Resume | Snapshot |
| --- | --- | --- |
| Impact on the original sandbox | Pause the original sandbox | The original sandbox will be paused briefly and then continue to run |
| Relationship | One-to-one: The same sandbox is restored | One-to-many: One snapshot can create multiple new sandboxes |
| Applicable scenarios | Suspend and later resume a single sandbox | Create reusable checkpoints |

To pause and resume the same sandbox, please refer to [Sandbox Persistence](/docs/agent-sandbox/sandbox/persistence.md).

## Snapshot process

```mermaid actions={false}
graph LR
    A[Running sandbox] -->|createSnapshot| B[Creating snapshot]
    B --> C[Snapshot has been created]
    B --> A
    C -->|Sandbox.create| D[New Sandbox 1]
    C -->|Sandbox.create| E[New Sandbox 2]
    C -->|Sandbox.create| F[New sandbox N]
```

The sandbox will pause briefly while the snapshot is being created and will automatically return to running state when complete. After the snapshot is completed, the original sandbox ID remains unchanged.

> The sandbox will briefly pause and resume while the snapshot is being taken. This can cause active connections to be dropped, such as WebSocket, PTY, command streams, etc. Please ensure that the client has the ability to reconnect.

## Create snapshot

You can create snapshots from a running sandbox instance.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

# Create a snapshot from a running sandbox
snapshot = sandbox.create_snapshot()
print("Snapshot ID:", snapshot.snapshot_id)
```

Snapshots can also be created by calling static methods with a sandbox ID.

```python
from ucloud_sandbox import Sandbox

sandbox_id = "your-sandbox-id"

# Create a snapshot by sandbox ID
snapshot = Sandbox.create_snapshot(sandbox_id)
print("Snapshot ID:", snapshot.snapshot_id)
```

## Create a sandbox from a snapshot

The snapshot ID can be passed directly to `Sandbox.create()` to create a new sandbox started from the snapshot state. The new sandbox will have the file system and memory state at the time the snapshot was captured.

```python
from ucloud_sandbox import Sandbox

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

# Create new sandbox from snapshot
new_sandbox = Sandbox.create(snapshot.snapshot_id)
print("New sandbox ID:", new_sandbox.sandbox_id)
```

## List snapshots

You can list all snapshots under the current account. This method returns a pager, suitable for traversing many results.

```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)
```

### Filter by sandbox

You can also query only snapshots created by a certain sandbox.

```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)
```

## Delete snapshot

Snapshots that are no longer needed should be deleted promptly to free up persistent storage.

```python
from ucloud_sandbox import Sandbox

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

Sandbox.delete_snapshot(snapshot.snapshot_id)
```

## Snapshots and templates

Snapshots and [templates](/docs/agent-sandbox/template/quickstart.md) can both be used as starting points for creating a sandbox, but they solve different problems.

| | Template | Snapshot |
| --- | --- | --- |
| How to define | Define the environment through declarative code | Capture the running sandbox |
| Reproducibility | The same definition will build a consistent base environment | Capture the runtime state that has occurred at a certain moment |
| Suitable for scenarios | Standardized, repeatable basic environment | Checkpoint, rollback, fork running status |

Templates such as pre-installed tools, fixed configurations, and consistent dependency environments should be used when you want each sandbox to start with the same, known, repeatable base environment.

Snapshots should be used when you need to capture or fork a real-time state that has already been run, such as when a task is halfway through execution, intermediate results are in memory, and a service has been started.

## Typical scenario

- **Save Agent Work Checkpoint**: The AI ​​Agent has loaded data and produced intermediate results in memory, can create a snapshot, and then continue or fork from that state.
- **Create rollback point**: Create a snapshot before performing high-risk or high-cost operations, such as running untrusted code, performing migrations, and reconstructing applications; if it fails, you can create a new sandbox from the snapshot to return to the pre-operation state.
- **Forked Workflow**: Create multiple sandboxes from the same snapshot and try different scenarios in parallel.
- **Cached runtime environment**: Create a snapshot of the sandbox that has completed expensive initialization to avoid subsequent repeated installation of dependencies, loading large data sets, or starting long processes.
- **Shared running state**: One user or Agent creates a snapshot after configuring the environment, and other users or Agents can start from the exact same state.