# 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 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](https://www.daytona.io/docs/en/v2/images.md#capture-images) instead. To register a registry image or a Dockerfile build under a name, [pull](https://www.daytona.io/docs/en/v2/images.md#pull-images) or [build](https://www.daytona.io/docs/en/v2/images.md#build-images) 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.


```bash
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.


```bash
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](https://www.daytona.io/docs/en/v2/linux-sandboxes.md#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](https://www.daytona.io/docs/en/v2/linux-sandboxes.md#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. |


```bash
daytona sandbox create-from-snapshot my-snapshot
```

- Reference the snapshot by name or by ID, **`snap_...`**.


```bash
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](https://www.daytona.io/docs/en/v2/linux-sandboxes.md#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)
}
```


```bash
daytona snapshot list
```


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


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


```bash
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' })`**.


```bash
daytona snapshot get {snapshotId}
```

- The command takes the snapshot ID, **`snap_...`**, not the name.


```bash
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 ↗](https://app.daytona.com/dashboard/snapshots)
2. Open the actions menu of a snapshot and click <Button>Delete</Button>
3. Click <Button>Delete</Button> 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}')
```


```bash
daytona snapshot delete {snapshotId}
```

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


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