---
title: Snapshots
description: 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 sandbox served from a warm template can be captured. A GPU sandbox produces a [checkpoint](/docs/v2/gpu-sandboxes) 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](/docs/v2/gpu-sandboxes). 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](/docs/v2/images#capture-images) instead. To register a registry image or a Dockerfile build under a name, [pull](/docs/v2/images#pull-images) or [build](/docs/v2/images#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.                 |
| **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 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.
- **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.

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

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

<Callout type="note" title="Notes">
- The sandbox must be running.
- On a Linux sandbox, this call captures kind `full`, which requires a sandbox served from a warm template.
- This call does not support Windows sandboxes.
</Callout>

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

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

<Callout type="note" title="Notes">
- The sandbox must be running.
- On a Linux sandbox, this call captures kind `full`, which requires a sandbox served from a warm template.
- This call does not support Windows sandboxes.
</Callout>

</TabItem>
<TabItem label="CLI" icon="seti:shell">

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

<Callout type="note" title="Notes">
- The command exits with an error if the capture fails.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

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

<Callout type="note" title="Notes">
- The sandbox must be running.
- On Linux, the call captures only a sandbox served from a warm template.
</Callout>

</TabItem>
</Tabs>

| **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.                    |
| **`checkpoint`** | Processes, memory, and GPU memory of a GPU sandbox   | Resumes in a new GPU sandbox. See [GPU sandboxes](/docs/v2/gpu-sandboxes).                                                                                          |

| **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.

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```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](/docs/v2/linux-sandboxes#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. |

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```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](/docs/v2/linux-sandboxes#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. |

</TabItem>
<TabItem label="CLI" icon="seti:shell">

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

<Callout type="note" title="Notes">
- Reference the snapshot by name or by ID, `snap_...`.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

```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](/docs/v2/linux-sandboxes#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. |

</TabItem>
</Tabs>

## Operations

### List snapshots

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

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

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

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

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona snapshot list
```

</TabItem>
<TabItem label="API" icon="seti:json">

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

</TabItem>
</Tabs>

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

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

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

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

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

</TabItem>
<TabItem label="CLI" icon="seti:shell">

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

</TabItem>
<TabItem label="API" icon="seti:json">

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

</TabItem>
</Tabs>

### Get a snapshot

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

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

<Callout type="note" title="Notes">
- `get` takes the snapshot ID, `snap_...`, not the name.
- To find a snapshot by name, call `daytona.v2.snapshots.list(name="my-snapshot")`.
</Callout>

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

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

<Callout type="note" title="Notes">
- `get` takes the snapshot ID, `snap_...`, not the name.
- To find a snapshot by name, call `daytona.v2.snapshots.list({ name: 'my-snapshot' })`.
</Callout>

</TabItem>
<TabItem label="CLI" icon="seti:shell">

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

<Callout type="note" title="Notes">
- The command takes the snapshot ID, `snap_...`, not the name.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

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

<Callout type="note" title="Notes">
- The path takes the snapshot ID, `snap_...`, not the name.
- To find a snapshot by name, call `GET /snapshots?name=my-snapshot`.
</Callout>

</TabItem>
</Tabs>

### 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

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

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

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

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

</TabItem>
<TabItem label="CLI" icon="seti:shell">

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

<Callout type="note" title="Notes">
- The command asks for confirmation.
- A non-interactive shell requires `--yes`.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

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

</TabItem>
</Tabs>