Snapshots

Daytona v2

Documentation for Daytona v2, currently in alpha. For the latest release, see Daytona v0.

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 sandbox served from a warm template can be captured. A snapshot restores only in its home region, on the runner that captured it. 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.

Concept	Description
Full snapshot	Kind full. The memory and disk of a running Linux sandbox that is served from a warm template.
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 running 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.
• 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.

Python

from daytona import Daytona

daytona = Daytona()
# Snapshot capture needs a sandbox served from a warm template (see the notes)
sandbox = daytona.v2.create("my-image")

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.

• The sandbox must be running.
• On a Linux sandbox, this call captures kind full, which requires a sandbox served from a warm template.

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()
// Snapshot capture needs a sandbox served from a warm template (see the notes)
const sandbox = await daytona.v2.create('my-image')

const snapshot = await sandbox.createSnapshot('my-snapshot')
console.log(snapshot.id, snapshot.kind, snapshot.status)

Parameter	Type	Description
name	string	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.

• The sandbox must be running.
• On a Linux sandbox, this call captures kind full, which requires a sandbox served from a warm template.

CLI

daytona snapshot create {sandboxId} --name my-snapshot

Flag	Type	Description
--name	string	Sets the snapshot name. This flag is required.
--timeout	string	Sets how long the command waits for the snapshot to be ready. The default is 10m.
--no-wait	boolean	Returns once the capture is queued, without waiting for ready.

• The command exits with an error if the capture fails.

API

curl 'https://api.daytona.com/sandboxes/{sandboxId}/snapshots' \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "my-snapshot" }'

The response has the following fields:

Field	Description
id	Identifies the new snapshot.
status	The status is pending. To wait, call GET /snapshots/{snapshotId}?wait=ready&timeout_ms=60000. It answers 200 at ready or failed, or when the wait expires. timeout_ms defaults to 30000 and is at most 60000.

• The sandbox must be running.
• On Linux, the call captures only a sandbox served from a warm template.

Kind	Captures	Restore behavior
full	Memory and disk of a Linux sandbox	Resumes the captured processes and memory. Requires a sandbox served from a warm template. Pinned to the region and to the runner that captured it.

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.

Python

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_policy	LifecyclePolicyConfig	Sets the lifecycle policy. It takes the same fields as lifecycle_policy in create a Linux sandbox.
ports	Sequence[PortMapping]	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_seconds	int	Sets the wait time in seconds. The default is 60.
create_timeout_seconds	int	Sets how many seconds the sandbox has to reach running before it is deleted. The default is 3600, and the maximum is 86400.

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const sandbox = await daytona.v2.createFromSnapshot('my-snapshot')

Parameter	Type	Description
snapshot	string	Sets the snapshot to restore from, by name or by ID, snap_.... This parameter is required.
name	string	Sets the display name. If omitted, a name is generated.
labels	Record<string, string>	Attaches key-value metadata to the sandbox.
lifecyclePolicy	LifecyclePolicyOptions	Sets the lifecycle policy. It takes the same fields as lifecyclePolicy in create a Linux sandbox.
ports	PortMapping[]	Forwards inbound ports to the sandbox.
region	string	Sets the region or global region slug. The default is the project default.
waitSeconds	number	Sets the wait time in seconds. The default is 60.
createTimeoutSeconds	number	Sets how many seconds the sandbox has to reach running before it is deleted. The default is 3600, and the maximum is 86400.

CLI

daytona sandbox create-from-snapshot my-snapshot

• Reference the snapshot by name or by ID, snap_....

API

curl 'https://api.daytona.com/sandboxes/from-snapshot' \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "snapshot": "my-snapshot" }'

Field	Type	Description
snapshot	string	Sets the snapshot to restore from, by name or by ID, snap_.... This field is required.
name	string	Sets the display name. If omitted, a name is generated.
labels	object	Attaches key-value metadata to the sandbox.
lifecycle_policy	object	Sets the lifecycle policy. It takes the same fields as lifecycle_policy in create a Linux sandbox.
ports	array	Forwards inbound ports to the sandbox.
region	string	Sets the region or global region slug. The default is the project default.
idempotency_key	string	Makes a retried create return the same sandbox. You can also send it as the Idempotency-Key header.
create_timeout_seconds	integer	Sets how many seconds the sandbox has to reach running before it is deleted. The default is 3600, and the maximum is 86400.
wait_seconds	integer	Sets how long the server holds the request for the sandbox to start. By default, the server holds it for at most 3 seconds.

Operations

List snapshots

Python

from daytona import Daytona

daytona = Daytona()

page = daytona.v2.snapshots.list()
for snapshot in page.items:
    print(snapshot.name, snapshot.kind, snapshot.status)

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const page = await daytona.v2.snapshots.list()
for (const snapshot of page.items) {
  console.log(snapshot.name, snapshot.kind, snapshot.status)
}

CLI

daytona snapshot list

API

curl 'https://api.daytona.com/snapshots' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Field	Description
id	Snapshot ID.
name	Unique name within the project. Used for restore.
class	linux.
kind	full.
status	pending, capturing, ready, or failed.
sandbox_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.
memory_bytes	Size of the captured memory, full only.
error	Failure reason when status is failed.

Iterate over all snapshots

Python

from daytona import Daytona

daytona = Daytona()

for snapshot in daytona.v2.snapshots.iter():
    print(snapshot.name, snapshot.kind, snapshot.status)

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

for await (const snapshot of daytona.v2.snapshots.iter()) {
  console.log(snapshot.name, snapshot.kind, snapshot.status)
}

CLI

# Follow every page until the server returns no cursor
daytona snapshot list --all

API

curl 'https://api.daytona.com/snapshots?cursor={next_cursor}' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Get a snapshot

Python

from daytona import Daytona

daytona = Daytona()

snapshot = daytona.v2.snapshots.get("{snapshotId}")
print(snapshot.kind, snapshot.status)

• get takes the snapshot ID, snap_..., not the name.
• To find a snapshot by name, call daytona.v2.snapshots.list(name="my-snapshot").

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const snapshot = await daytona.v2.snapshots.get('{snapshotId}')
console.log(snapshot.kind, snapshot.status)

• get takes the snapshot ID, snap_..., not the name.
• To find a snapshot by name, call daytona.v2.snapshots.list({ name: 'my-snapshot' }).

CLI

daytona snapshot get {snapshotId}

• The command takes the snapshot ID, snap_..., not the name.

API

curl 'https://api.daytona.com/snapshots/{snapshotId}' \
  --header 'Authorization: Bearer YOUR_API_KEY'

• The path takes the snapshot ID, snap_..., not the name.
• To find a snapshot by name, call GET /snapshots?name=my-snapshot.

Delete snapshots

Delete a snapshot. It cannot be deleted while a sandbox restored from it exists.

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

Python

from daytona import Daytona

daytona = Daytona()

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

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

await daytona.v2.snapshots.delete('{snapshotId}')

CLI

daytona snapshot delete {snapshotId}

• The command asks for confirmation.
• A non-interactive shell requires --yes.

API

curl 'https://api.daytona.com/snapshots/{snapshotId}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_API_KEY'