> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Save and restore sandbox state with snapshots

> Create a snapshot of a running sandbox, start new sandboxes from it, list and filter snapshots, and delete the ones no longer needed.

A snapshot is a reusable saved state of a sandbox. It captures the sandbox filesystem and memory state, so a new sandbox can start from that point later with the setup work already done.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

> [!NOTE]
>
> Snapshots are available only in some regions.

## What a snapshot contains

A snapshot captures the state of a running sandbox at a moment in time: the filesystem and the live memory state, including anything created at runtime. Snapshots are persistent and remain available after the source sandbox is deleted.

Use snapshots to:

* Prepare dependencies once and reuse them in later sandboxes.
* Save a known-good state before running risky or expensive work.
* Start multiple sandboxes from the same captured environment.
* Keep a reusable state after the original sandbox is no longer needed.

## Snapshots and templates

Snapshots and templates both start new sandboxes from a predefined point, but they differ in how that point is produced and what it captures.

| | Template | Snapshot |
| - | - | - |
| Produced by | A build from a Docker image with declared steps: install packages, copy files, set environment variables | A capture of a running sandbox at a moment in time |
| What it holds | A clean, reproducible blueprint authored up front | The filesystem and live memory state, including files created at runtime |
| Use it for | A reproducible base environment | The exact state of a specific sandbox |

The three terms form a chain:

```mermaid theme={null}
flowchart LR
  O[Origin sandbox] -->|create the snapshot| S[Snapshot]
  S -->|create new sandboxes| N[New sandbox]
```

## Create a snapshot and start a sandbox from it

> [!WARNING]
>
> The sandbox is paused while the snapshot is being created.

In the console, a snapshot is created with the row action **Save as snapshot**; see [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md).

**1. Create the snapshot**

Call `create_snapshot()` on a running sandbox after the state to preserve is in place.

```python Python theme={null}
# Prepare state you want to preserve
sandbox.commands.run("pip install requests")

# Capture the current state (the sandbox is paused during this)
snapshot = sandbox.create_snapshot()
print("Snapshot ID:", snapshot.snapshot_id)
```

```javascript Node.js theme={null}
// Prepare state you want to preserve
await sandbox.commands.run('pip install requests')

// Capture the current state (the sandbox is paused during this)
const snapshot = await sandbox.createSnapshot()
console.log('Snapshot ID:', snapshot.snapshotId)
```

**2. Start a sandbox from the snapshot**

Pass the snapshot ID to `create()`. The captured state is already present, so the setup work does not run again.

```python Python theme={null}
# Create a new sandbox from a previously captured snapshot
new_sandbox = ppio.sandbox.create(snapshot_id)

# The state captured in the snapshot is already present
result = new_sandbox.commands.run("python -c 'import requests; print(requests.__version__)'")
print(result.stdout)

new_sandbox.kill()
```

```javascript Node.js theme={null}
// Create a new sandbox from a previously captured snapshot
const newSandbox = await ppio.sandbox.create(snapshotId)

// The state captured in the snapshot is already present
const result = await newSandbox.commands.run("python -c 'import requests; print(requests.__version__)'")
console.log(result.stdout)

await newSandbox.kill()
```

### Full example

In the CLI example, `<sandbox-id>` is the ID of the sandbox to capture.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create("base")

# Prepare state you want to preserve
sandbox.commands.run("pip install requests")

# Capture the current state (the sandbox is paused during this)
snapshot = sandbox.create_snapshot()
print("Snapshot ID:", snapshot.snapshot_id)

snapshot_id = snapshot.snapshot_id

# Create a new sandbox from a previously captured snapshot
new_sandbox = ppio.sandbox.create(snapshot_id)

# The state captured in the snapshot is already present
result = new_sandbox.commands.run("python -c 'import requests; print(requests.__version__)'")
print(result.stdout)

new_sandbox.kill()
sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create('base')

// Prepare state you want to preserve
await sandbox.commands.run('pip install requests')

// Capture the current state (the sandbox is paused during this)
const snapshot = await sandbox.createSnapshot()
console.log('Snapshot ID:', snapshot.snapshotId)

const snapshotId = snapshot.snapshotId

// Create a new sandbox from a previously captured snapshot
const newSandbox = await ppio.sandbox.create(snapshotId)

// The state captured in the snapshot is already present
const result = await newSandbox.commands.run("python -c 'import requests; print(requests.__version__)'")
console.log(result.stdout)

await newSandbox.kill()
await sandbox.kill()
```

```bash CLI theme={null}
ppio snapshot create <sandbox-id>
```

## Create a snapshot by sandbox ID

A snapshot can be created without a sandbox handle by passing the sandbox ID to the same method on the namespace. In the examples, `<sandbox-id>` is the sandbox ID.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox_id = "<sandbox-id>"
snapshot = ppio.sandbox.create_snapshot(sandbox_id=sandbox_id)
print("Snapshot ID:", snapshot.snapshot_id)
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandboxId = '<sandbox-id>'
const snapshot = await ppio.sandbox.createSnapshot(sandboxId)
console.log('Snapshot ID:', snapshot.snapshotId)
```

## List snapshots

Call the method and page through the results. Each page is a list of `SnapshotInfo`.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
paginator = ppio.sandbox.list_snapshots(limit=20)

while paginator.has_next:
    snapshots = paginator.next_items()
    for s in snapshots:
        print(s.snapshot_id)
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const paginator = ppio.sandbox.listSnapshots({ limit: 20 })

while (paginator.hasNext) {
  const snapshots = await paginator.nextItems()
  for (const s of snapshots) {
    console.log(s.snapshotId)
  }
}
```

```bash CLI theme={null}
# List snapshots (pretty table output by default)
ppio snapshot list

# JSON output
ppio snapshot list --output json
```

### Filter by source sandbox

Pass a sandbox ID to list only the snapshots created from that sandbox.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox_id = "<sandbox-id>"
paginator = ppio.sandbox.list_snapshots(sandbox_id=sandbox_id)

while paginator.has_next:
    for s in paginator.next_items():
        print(s.snapshot_id)
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandboxId = '<sandbox-id>'

const paginator = ppio.sandbox.listSnapshots({ sandboxId })

while (paginator.hasNext) {
  for (const s of await paginator.nextItems()) {
    console.log(s.snapshotId)
  }
}
```

## Delete a snapshot

Delete a snapshot by its ID. The call returns `true` if the snapshot was deleted, or `false` if no snapshot with that ID was found.

> [!WARNING]
>
> Deleting a snapshot is permanent. Sandboxes already created from it are unaffected, but no new sandbox can be created from it afterwards. Deleting a snapshot can fail while sandboxes created from it are running. Kill those sandboxes before deleting the snapshot.

In the examples, `<snapshot-id>` is the snapshot ID.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
snapshot_id = "<snapshot-id>"
deleted = ppio.sandbox.delete_snapshot(snapshot_id)
print("deleted" if deleted else "not found")
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const deleted = await ppio.sandbox.deleteSnapshot('<snapshot-id>')
console.log(deleted ? 'deleted' : 'not found')
```

```bash CLI theme={null}
ppio snapshot delete <snapshot-id>
```


## Related topics

- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)
- [What is a sandbox template?](https://docs.ppio.ai/sandbox/templates/overview.md)
- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.