Snapshots

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

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

• 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 (SDK) or sandbox fork (CLI).

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 (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, and they keep incurring storage charges in the meantime.

A snapshot isn't tied to one sandbox. You can create or 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 and Persistent sandboxes.

You create snapshots in one of two ways:

Once created, a snapshot reports a status that you can read with Snapshot.get or Snapshot.list:

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

Call snapshot() on a running sandbox:

# Create a snapshot of a running sandbox (by name)
sandbox snapshot my-sandbox --stop
 
# Create a snapshot that expires 14 days after its last use
sandbox snapshot my-sandbox --stop --expiration 14d
 
# Create a snapshot that never expires
sandbox snapshot my-sandbox --stop --expiration 0

import { Sandbox } from '@vercel/sandbox';
import ms from 'ms';
 
const sandbox = await Sandbox.create();
 
// Install dependencies, configure environment, etc.
await sandbox.runCommand('npm', ['install']);
 
// Snapshot and get the ID
const snapshot = await sandbox.snapshot({ expiration: ms('14d') });
console.log(snapshot.snapshotId);

import asyncio
from datetime import timedelta
 
from vercel import sandbox
 
 
async def main() -> None:
    box = await sandbox.create_sandbox()
 
    # Install dependencies, configure environment, etc.
    await box.run_process("uv", ["sync"], check=True)
 
    # Snapshot and get the ID.
    snapshot = await box.snapshot(expiration=timedelta(days=14))
    print(snapshot.id)
 
 
asyncio.run(main())

Pass the snapshot ID when creating a new sandbox:

sandbox create --snapshot snap_abc123

const sandbox = await Sandbox.create({
  source: { type: 'snapshot', snapshotId: 'snap_abc123' },
});

import asyncio
 
from vercel import sandbox
from vercel.sandbox import SnapshotSource
 
 
async def main() -> None:
    box = await sandbox.create_sandbox(
        source=SnapshotSource(snapshot_id="snap_abc123")
    )
    print(box.current_snapshot_id)
 
 
asyncio.run(main())

A snapshot is stored in the region of the sandbox it was created from. You can only create or resume a sandbox from a snapshot in a region where that snapshot is available. Creating a sandbox from a snapshot in another region fails with a snapshot_region_mismatch error. Failover is the exception. When creation falls back to a failover region, Vercel loads the snapshot from the closest region where it's available.

Snapshots can't be moved between regions. To run an environment in another region, create a new sandbox in that region, run your setup again, and snapshot it there.

Read the regions where a snapshot is available with the snapshot.regions accessor in the SDK, or from the REGIONS column of sandbox snapshots list in the CLI. Snapshot storage is billed at the same rate in every region.

View all snapshots for your project:

# List snapshots for the current project
sandbox snapshots list
 
# List snapshots for a specific project
sandbox snapshots list --project my-app

import { Snapshot } from '@vercel/sandbox';
 
// Auto-paginates through every page
const result = await Snapshot.list();
for await (const snapshot of result) {
  console.log(snapshot.id, snapshot.status);
}
 
// Or filter by sandbox name
const forSandbox = await Snapshot.list({ name: 'my-sandbox' });

import asyncio
 
from vercel import sandbox
 
 
async def main() -> None:
    async for snapshot in sandbox.query_snapshots(page_size=10):
        print(snapshot.id, snapshot.status)
 
 
asyncio.run(main())

Look up a snapshot by ID:

sandbox snapshots list

import { Snapshot } from '@vercel/sandbox';
 
const snapshot = await Snapshot.get({ snapshotId: 'snap_abc123' });
console.log(snapshot.status); // "created" | "deleted" | "failed"

import asyncio
 
from vercel import sandbox
 
 
async def main() -> None:
    snapshot = await sandbox.get_snapshot(snapshot_id="snap_abc123")
    print(snapshot.status)
 
 
asyncio.run(main())

Remove snapshots you no longer need:

# Delete a single snapshot
sandbox snapshots delete snap_abc123
 
# Delete multiple snapshots
sandbox snapshots delete snap_abc123 snap_def456

await snapshot.delete();

import asyncio
 
from vercel import sandbox
 
 
async def main() -> None:
    snapshot = await sandbox.get_snapshot(snapshot_id="snap_abc123")
    await snapshot.delete()
 
 
asyncio.run(main())

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 (the default), the SDK creates a snapshot every time a session stops, so a retention policy is how you keep storage flat.

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.

• Snapshots expire 30 days after their last use by default. See Snapshot states for how expiration moves a snapshot to deleted.
• Snapshots can only be used in a region where they are available. See Snapshots and regions.
• See Pricing and Limits for storage costs and limits.