---
title: Snapshots
product: vercel
url: /docs/sandbox/concepts/snapshots
canonical_url: "https://vercel.com/docs/sandbox/concepts/snapshots"
last_updated: 2026-08-04
type: conceptual
prerequisites:
  - /docs/sandbox/concepts
  - /docs/sandbox
related:
  - /docs/sandbox/concepts/persistent-sandboxes
  - /docs/sandbox/sdk-reference
  - /docs/sandbox/cli-reference
  - /docs/sandbox/pricing
  - /docs/sandbox/concepts
summary: Save and restore sandbox state with snapshots for faster startups and environment sharing.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Snapshots

Snapshots capture the state of a running sandbox, including the filesystem and installed packages. Use snapshots to skip setup time on subsequent runs.


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [How to use snapshots for faster sandbox startup](https://vercel.com/kb/guide/how-to-use-snapshots-for-faster-sandbox-startup?from=related) — Learn how to save sandbox state with snapshots and skip installation on future runs.
- [The Complete Guide to Vercel Drives](https://vercel.com/kb/guide/vercel-drives?from=related) — Learn how Vercel Drives provide persistent storage for Vercel Sandboxes, and how to create, mount, list, and delete a dr
- [How Vercel Sandbox duration and persistence work](https://vercel.com/kb/guide/vercel-sandbox-duration-and-persistence?from=related) — Session duration and persistence are two separate controls in Vercel Sandbox. The timeout option keeps a single run aliv
- [How to reconnect to a running Sandbox](https://vercel.com/kb/guide/how-to-reconnect-to-a-running-sandbox?from=related) — Learn how to use \`Sandbox.get\(\)\` to reconnect to an existing sandbox from a different process or after a script rest
- [Examples](https://vercel.com/docs/sandbox/working-with-sandbox?from=related) — Task-oriented examples for common Vercel Sandbox operations in TypeScript and Python.
- [Create a snapshot](https://vercel.com/docs/rest-api/sandboxes/create-a-snapshot?from=related)
- [vercel sandbox](https://vercel.com/docs/cli/sandbox?from=related) — Interact with Vercel Sandbox from the Vercel CLI: list, create, connect, exec, copy, stop, and snapshot sandboxes from y
- [List snapshots](https://vercel.com/docs/rest-api/sandboxes/list-snapshots?from=related)
- [Get a snapshot](https://vercel.com/docs/rest-api/sandboxes/get-a-snapshot?from=related)

Full cross-link map for this page: [/docs/sandbox/concepts/snapshots.graph.md](/docs/sandbox/concepts/snapshots.graph.md)
<!-- /docsgraph:related -->

For [persistent sandboxes](/docs/sandbox/concepts/persistent-sandboxes) (the default), snapshots are created automatically whenever a session stops, and the next session resumes from the most recent snapshot. You can still call `snapshot()` manually to create a checkpoint between sessions, or to fork a child sandbox from a known state.

## When to use snapshots

- **Faster startups**: Skip dependency installation by snapshotting after setup.
- **Checkpointing**: Save progress on long-running tasks.
- **Sharing environments**: Give teammates an identical starting point.
- **Forking**: Spawn new sandboxes from another sandbox's current state with [`Sandbox.fork`](/docs/sandbox/sdk-reference#sandbox.fork) (SDK) or [`sandbox fork`](/docs/sandbox/cli-reference#sandbox-fork) (CLI).

## How snapshots fit the sandbox lifecycle

A sandbox runs work inside a session, and snapshots connect one session to the next: when a session stops, its state is saved, and the next session resumes from that snapshot instead of starting clean.

The cycle looks like this:

1. You start or resume a sandbox, which runs a session.
2. When you call `stop()` or the timeout expires, the session stops. For a [persistent sandbox](/docs/sandbox/concepts/persistent-sandboxes) (the default), Vercel captures its filesystem and creates a snapshot automatically before the sandbox shuts down. Non-persistent sandboxes skip this and discard their filesystem.
3. When you create or resume a sandbox from a snapshot, it starts a new session from the saved state.

You can also snapshot a running sandbox at any time by calling `snapshot()`, which captures its current filesystem before stopping the session.

Snapshots outlive the sandbox they came from. Deleting a sandbox removes the sandbox and its sessions, but its snapshots stay available until they expire or you [delete them](#delete-a-snapshot), and they keep incurring [storage charges](/docs/sandbox/pricing#snapshot-storage) in the meantime.

A snapshot isn't tied to one sandbox. You can create or [fork](/docs/sandbox/sdk-reference#sandbox.fork) any number of sandboxes from the same snapshot, so deleting a single sandbox can't remove a snapshot that other sandboxes still start from.

For the full sandbox-side view of this cycle, see [Understanding Sandboxes](/docs/sandbox/concepts#sandbox-lifecycle) and [Persistent sandboxes](/docs/sandbox/concepts/persistent-sandboxes).

### How snapshots are created

You create snapshots in one of two ways:

| Creation method | When it happens                                                                 | How to control it                                                                                                          |
| :-------------- | :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
| **Automatic**   | A persistent sandbox session stops (manual `stop()` or timeout).                | Tune with [`snapshotExpiration`](/docs/sandbox/sdk-reference#snapshotexpiration) and [`keepLastSnapshots`](/docs/sandbox/sdk-reference#keeplastsnapshots). Opt out by making the sandbox non-persistent. |
| **Manual**      | You call `snapshot()` (SDK) or `sandbox snapshot --stop` (CLI) on a running sandbox. | Pass `expiration` to [`snapshot()`](/docs/sandbox/sdk-reference#sandbox.snapshot) per call to control when the snapshot expires. |

### Snapshot states

Once created, a snapshot reports a `status` that you can read with [`Snapshot.get`](#retrieve-an-existing-snapshot) or [`Snapshot.list`](#list-snapshots):

| Status      | Meaning                                                                                              |
| :---------- | :--------------------------------------------------------------------------------------------------- |
| `created`   | The snapshot is captured and ready to create or resume sandboxes from.                               |
| `deleted`   | The snapshot was removed, either because you called `delete()` or because it reached its expiration. |
| `failed`    | The capture didn't complete, so the snapshot can't be used. Take a new snapshot to retry.            |

When a snapshot's expiration passes, it moves to `deleted`. The [retention settings](#snapshot-retention) control that expiration, and each time you create a sandbox from a snapshot, its expiration timer resets, so snapshots you keep using stay `created`.

## Create a snapshot

Call `snapshot()` on a running sandbox:

> **💡 Note:** Once you create a snapshot, the sandbox shuts down automatically and becomes unreachable. You don't need to stop it afterwards.

## Create a sandbox from a snapshot

Pass the snapshot ID when creating a new sandbox:

## List snapshots

View all snapshots for your project:

## Retrieve an existing snapshot

Look up a snapshot by ID:

## Delete a snapshot

Remove snapshots you no longer need:

## Snapshot retention

Snapshots expire **30 days after their last use** by default. You can shorten, extend, or remove that expiration at three levels:

- **Per-call**: pass `expiration` to `sandbox.snapshot({ expiration })` or `--expiration` to `sandbox snapshot`. Use `0` (or `none` in the CLI) for no expiration.
- **Per-sandbox default**: set `snapshotExpiration` at the sandbox level. Every automatic snapshot taken on stop, and every manual snapshot that omits an explicit `expiration`, inherits this value.
- **Retention policy**: use `keepLastSnapshots` to bound how many snapshots a sandbox keeps, regardless of expiration. For [persistent sandboxes](/docs/sandbox/concepts/persistent-sandboxes) (the default), the SDK creates a snapshot every time a session stops, so a retention policy is how you keep storage flat.

```ts
await sandbox.update({
  snapshotExpiration: 7 * 24 * 60 * 60 * 1000, // 7 days
  keepLastSnapshots: { count: 1, expiration: 30 * 24 * 60 * 60 * 1000 },
});
```

`keepLastSnapshots` fields:

- `count`: keep only the N (1–10) most recent snapshots.
- `expiration`: TTL for the kept snapshots, in milliseconds. Use `0` for no expiration.
- `deleteEvicted`: when `true` (the default), evicted snapshots are deleted immediately.

## Snapshot limits

- Snapshots expire **30 days after their last use** by default. See [Snapshot states](#snapshot-states) for how expiration moves a snapshot to `deleted`.
- See [Pricing and Limits](/docs/sandbox/pricing#snapshot-storage) for storage costs and limits.


---

[View full sitemap](/docs/sitemap)