Snapshots
Captures of the memory and disk of a running sandbox that new sandboxes resume from.
A snapshot is a capture of the memory and disk of a running sandbox, saved under a name. A sandbox restored from a snapshot resumes the captured processes and memory instead of booting. Deleting the source sandbox does not affect its snapshots.
A Linux sandbox produces a full snapshot, and only a persistent sandbox or one served from a warm template can be captured. A GPU sandbox produces a checkpoint that also holds GPU memory. A snapshot restores only in its home region. A full snapshot restores only on the runner that captured it. A checkpoint restores on any GPU runner in the region that meets the restore requirements. Windows and macOS sandboxes do not support snapshots.
A snapshot holds a running state. To save only the filesystem of a sandbox, capture an image instead. To register a registry image or a Dockerfile build under a name, pull or build an image.
| Concept | Description |
|---|---|
| Full snapshot | Kind full. The memory and disk of a running Linux sandbox that is persistent or served from a warm template. |
| Checkpoint | Kind checkpoint. The processes, memory, and GPU memory of a running GPU sandbox. |
| Restore | A new sandbox that resumes the captured processes and memory, with the CPU, memory, and disk of the source. |
| Home region | The region of the source sandbox. A snapshot restores only there, on the runner that captured it. |
| Name | Unique in the project. Snapshots and images share one name space. |
Use cases
Snapshots are used when a new sandbox must continue from a running state instead of booting and repeating its setup.
- Checkpoints of running work: a full snapshot saves the memory and disk of a persistent sandbox. A restore resumes the captured processes instead of starting them again.
- Fast starts for slow-booting programs: a full snapshot taken after a server, a kernel, or a model has loaded restores with that program already running. New sandboxes skip the load time.
- Evaluation and reinforcement learning (RL): each test case or episode resumes from the same snapshot. Results do not depend on another run.
- Long GPU jobs: a checkpoint saves a GPU job together with its GPU memory. A new GPU sandbox resumes the job from the point it was saved.
- Parallel attempts from one state: several sandboxes restore from the same snapshot, and each continues on its own. An agent tries several approaches from one point without repeating the setup.
- Debugging and reproduction: a snapshot captures a sandbox in the state where a problem occurs. A restored sandbox reproduces that state, with its processes and memory, for inspection.
- State that outlives the sandbox: deleting the source sandbox does not affect its snapshots. The sandbox is deleted to free its resources, and its state is restored later in its home region.
Create snapshots
Create a snapshot of a running sandbox. The capture runs in the background: the snapshot starts as pending and becomes ready when the capture finishes.
from daytona import Daytona
daytona = Daytona()
sandbox = daytona.v2.create("my-image", persistent=True)
snapshot = sandbox.create_snapshot("my-snapshot")
print(snapshot.id, snapshot.kind, snapshot.status)| Parameter | Type | Description |
|---|---|---|
name | str | Sets the snapshot name, 1 to 128 characters of letters, digits, ., _, and -. Snapshots and images in the project share one name space. A name in use fails with 409. This parameter is required. |
The response has the following fields:
| Field | Description |
|---|---|
status | The status is pending, because the call returns once the capture is queued. To wait, call daytona.v2.snapshots.get(snapshot.id, wait="ready"). It returns at ready or failed, or after the server wait. The server wait is 30 seconds by default, and timeout sets it in seconds, up to 60. |
| Kind | Captures | Restore behavior |
|---|---|---|
full | Memory and disk of a Linux sandbox | Resumes the captured processes and memory. Requires a persistent sandbox, or one served from a warm template. Pinned to the region and to the runner that captured it. |
checkpoint | Processes, memory, and GPU memory of a GPU sandbox | Resumes in a new GPU sandbox. See checkpoints. |
| Status | Meaning |
|---|---|
pending | Accepted; the capture job is queued on the sandbox's runner. |
capturing | The runner is pausing, copying, and packing the sandbox state. |
ready | Restorable. |
failed | Terminal. error carries the reason. The source sandbox keeps running. |
Restore snapshots
Restore a sandbox from a snapshot. It resumes the captured processes and memory and keeps the source sandbox's CPU, memory, and disk. A snapshot restores only in its home region, on the runner that captured it, and fails while that runner is unavailable.
from daytona import Daytona
daytona = Daytona()
sandbox = daytona.v2.create_from_snapshot("my-snapshot")| Parameter | Type | Description |
|---|---|---|
snapshot | str | Sets the snapshot to restore from, by name or by ID, snap_.... This parameter is required. |
name | str | Sets the display name. If omitted, a name is generated. |
labels | Dict[str, str] | Attaches key-value metadata to the sandbox. |
lifecycle | LifecycleConfig | Sets the lifecycle policy. It takes the same fields as lifecycle in create a Linux sandbox. |
ports | Sequence[PortRequest] | Forwards inbound ports to the sandbox. |
region | str | Sets the region or global region slug. The default is the project default. |
idempotency_key | str | Makes a retried create return the same sandbox. |
wait | int | Sets the wait time in seconds. The default is 60. |
create_ttl | int | Sets how many seconds the sandbox has to reach running before it is deleted. The default is 3600, and the maximum is 86400. |
Operations
List snapshots
from daytona import Daytona
daytona = Daytona()
page = daytona.v2.snapshots.list()
for snapshot in page.items:
print(snapshot.name, snapshot.kind, snapshot.status)| Field | Description |
|---|---|
id | Snapshot ID. |
name | Unique name within the project. Used for restore. |
class | linux or gpu. |
kind | full for Linux, or checkpoint for GPU. |
status | pending, capturing, ready, or failed. |
vm_id | The source sandbox. null once the source sandbox is deleted. |
region | Home region. The only region the snapshot can be restored in. |
available_in | Regions the snapshot can be restored in. Always [region]. |
bytes | Size of the snapshot in bytes. |
mem_bytes | Size of the captured memory, full only. |
error | Failure reason when status is failed. |
Iterate over all snapshots
from daytona import Daytona
daytona = Daytona()
for snapshot in daytona.v2.snapshots.iter():
print(snapshot.name, snapshot.kind, snapshot.status)Get a snapshot
from daytona import Daytona
daytona = Daytona()
snapshot = daytona.v2.snapshots.get("{snapshotId}")
print(snapshot.kind, snapshot.status)Delete snapshots
Delete a snapshot. It cannot be deleted while a sandbox restored from it exists.
- Go to Daytona Dashboard ↗
- Open the actions menu of a snapshot and click Delete
- Click Delete to confirm
from daytona import Daytona
daytona = Daytona()
daytona.v2.snapshots.delete("{snapshotId}")