Snapshots

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 full snapshot restores in its home region, on the runner that captured it or on another runner of the region with the same CPU model and hypervisor version. Where Daytona has enabled cross-region restore, a full snapshot of a sandbox that is not persistent can also restore in another region, which receives a copy of it first. Without it, a restore that names another region returns 400. A checkpoint restores on any GPU runner in the region that meets the restore requirements. Windows sandboxes do not support snapshots. macOS sandboxes do not produce these snapshots: a macOS filesystem snapshot saves the disk of a stopped persistent sandbox as an image, and it restores on any Mac of the region.

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.

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 running sandbox. A restore resumes the captured processes instead of starting them again. The capture runs in the background, and the source sandbox keeps running if the capture fails.

• 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. The program must run in a persistent Linux sandbox or one served from a warm template, because only those sandboxes can be captured.

• Evaluation and reinforcement learning (RL). Each test case or episode resumes from the same snapshot. Results do not depend on another run. Every restored sandbox keeps the CPU, memory, and disk of the source, so each run gets the same resources.

• 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. The checkpoint restores on any GPU runner in the region that meets the restore requirements.

• 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. The snapshot cannot be deleted while a sandbox restored from it exists.

Create snapshots

Create a snapshot of a running sandbox. The capture runs in the background: the snapshot starts as pending, is building while the runner captures the sandbox, and becomes ready when the capture finishes. Deleting the source sandbox during the capture fails the snapshot.

from daytona import Daytona

daytona = Daytona()
# Snapshot capture needs a persistent sandbox or one served from a warm template
sandbox = daytona.v2.create()

snapshot = sandbox.create_snapshot("my-snapshot")
print(snapshot.id, snapshot.kind, snapshot.status)

Restore snapshots

Restore a sandbox from a snapshot. It resumes the captured processes and memory and keeps the source sandbox's CPU, memory, disk, and persistence. The restore runs on the runner that captured the snapshot when that runner can take it, and otherwise on another runner of the region with the same CPU model and hypervisor version. Where cross-region restore is enabled, a restore in another region waits while the snapshot is copied there.

from daytona import Daytona

daytona = Daytona()

sandbox = daytona.v2.create_from_snapshot("my-snapshot")

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)

The API returns the following fields. The SDKs use the same names, except where the description says otherwise.

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, including a restored sandbox whose deletion has not finished.

1. Go to Daytona Dashboard ↗
2. Open the actions menu of a snapshot and click Delete
3. Click Delete to confirm

from daytona import Daytona

daytona = Daytona()

daytona.v2.snapshots.delete("{snapshotId}")

Errors

The SDKs raise these errors with the codes in the following table, and the API returns them in the code field.

Permissions

Snapshots are scoped to a project. Access is governed by three permissions, which you can grant to an organization role or an API key.

Restoring a snapshot creates a sandbox, so it requires the permission to create sandboxes. The audit logs record snapshot creates and deletes.