How Vercel Sandbox duration and persistence work

Vercel Sandbox gives each sandbox two independent lifetime controls: how long a single run can last, and whether its state survives between runs. Duration is set by the timeout option and governs one uninterrupted session, now up to 24 hours on Pro and Enterprise plans. Persistence is a separate mechanism that snapshots a sandbox when it stops and restores it when it resumes, so a sandbox can outlive any single session. Knowing which control does what lets you run long agents, data pipelines, and test suites without losing work when a run ends or paying for compute you aren't using.

In this guide, you'll learn:

• The difference between a sandbox and a session
• How the timeout option controls a single run, and the maximum on each plan
• How persistence preserves filesystem state across sessions using snapshots
• When to use longer duration, persistence, or both
• How each choice affects what you pay

Sandboxes are long-lived named entities in your project, and sessions are single running virtual machines (VMs) within them. The sandbox survives across many VM boots, while each session is one boot of that VM. When you resume a sandbox, a new session starts from the most recently saved state.

This distinction is the key to everything else on this page because the two lifetime controls operate at different levels. Duration limits a single session, while persistence carries a sandbox from one session to the next.

The timeout option on Sandbox.create() sets the duration of a session, defaulting to 5 minutes. You set the value in milliseconds, and when a session times out, Vercel stops it. The maximum you can configure depends on your plan, up to 24 hours on Pro and Enterprise and up to 45 minutes on Hobby.

1
import { Sandbox } from '@vercel/sandbox';
2

3
const sandbox = await Sandbox.create({
4
  timeout: 24 * 60 * 60 * 1000, // 24 hours, in milliseconds
5
});

Duration applies to one uninterrupted session. A longer timeout suits work that needs to run from start to finish without stopping, such as a large data-processing job, an end-to-end test pipeline, or a long-lived agent task.

You can extend a session that's already running with extendTimeout(), which adds time up to your plan's maximum. Check the timeout accessor first, since it reports the milliseconds left before the session stops, and extend only when the remaining window is too short.

// Add 60 seconds to the current session
await sandbox.extendTimeout(60 * 1000);

Extending a running session keeps a sandbox alive when a task runs longer than you first expected, without provisioning a long timeout up front.

Sandboxes are persistent by default, so when a session stops, the SDK snapshots the filesystem and the next resume boots a new session from that snapshot. The sandbox configuration is preserved across sessions and reapplied on resume, so you don't rebuild your environment each time.

const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  // persistent: true is the default. Pass false to opt out.
});

await sandbox.runCommand('npm', ['install']);
await sandbox.stop(); // Filesystem is snapshotted automatically

To work with a long-lived sandbox, use Sandbox.getOrCreate(). It resumes the sandbox if one with that name exists, or creates it if it doesn't. Pair it with two lifecycle hooks:

• onCreate runs once, the first time the sandbox is created, which is where one-time setup, like cloning a repo or installing dependencies belongs.
• onResume runs every time a session starts.

1
const sandbox = await Sandbox.getOrCreate({
2
  name: 'my-sandbox',
3
  runtime: 'node24',
4
  onCreate: async (sbx) => {
5
    // Runs once, on first creation
6
    await sbx.runCommand('git', ['clone', repoUrl, '.']);
7
    await sbx.runCommand('npm', ['install']);
8
  },
9
  onResume: async (sbx) => {
10
    // Runs on every resume
11
    await sbx.runCommand({ cmd: 'npm', args: ['run', 'dev'], detached: true });
12
  },
13
});

If you call a method like runCommand or writeFiles on a stopped persistent sandbox, the SDK starts a new session and retries the operation, so you don't need to check the status or restart it manually. A non-persistent sandbox, created with persistent: false, discards its filesystem when the session stops and doesn't accrue snapshot storage costs.

A snapshot records the sandbox's filesystem and installed packages, which lets a resumed session skip setup it has already done. By default, snapshots expire 30 days after their last use, and you can change that with snapshotExpiration. For a sandbox you resume often, a retention policy such as keepLastSnapshots: { count: 1 } keeps only the most recent snapshot, so storage stays flat.

Snapshots persist on the sandbox's own filesystem and are tied to its lifecycle, so they belong to the sandbox that created them and expire after 30 days by default.

When you need data that outlives the sandbox entirely, or that several sandboxes share, use a Vercel Drive instead. A drive is storage with a lifecycle independent of any sandbox. You create it once, mount it in a sandbox at a path you choose, and its contents stay put after the sandbox stops, ready for the next run to mount it. Drives suit caching, large datasets, and agent workspaces that grow across runs.

For the full comparison of snapshots and workflows, see the Vercel Drives guide.

Duration and persistence solve different problems, and most long-running workloads use both. Duration keeps one session alive for a single uninterrupted run, while persistence carries a sandbox's state across many sessions, including after a stop or an unexpected end. A long agent that should also survive interruptions can run with a high timeout and rely on persistence, so a single run can last hours, and a resume can continue from the last snapshot.

Reach for a longer duration when a job runs from start to finish in one session, such as large-scale data processing, an end-to-end test run, or an agent task that completes within 24 hours. Rely on persistence when work pauses and resumes over time, or when a sandbox must survive a stop without losing its filesystem, such as a development environment you reconnect to across days. Combine both for a long, agentic workflow that checkpoints its progress, so the run can last hours, and a later resume picks up where it left off.

Some workloads don't fit a sandbox. For a server that needs to stay continuously up, use a traditional VM or Vercel Functions rather than keeping a sandbox open. For long-term storage of large datasets, push data to a database or object store, since a persistent filesystem preserves state between sessions but isn't built to be your primary data store.

Two metering dimensions explain why a long run can still be inexpensive, and why an idle one is not free.

Because provisioned memory accumulates while a session is alive, stopping a persistent sandbox between bursts of work and resuming it later can cost less than keeping a single session open the whole time.

• Persistent sandboxes: the sandbox and session model, snapshot retention, and resume behavior in depth
• Snapshots: capture and restore a sandbox's filesystem and installed packages
• The Complete Guide to Vercel Drives: persistent storage that outlives a sandbox, for caching and data shared across runs
• JS SDK Reference: timeout, extendTimeout(), getOrCreate(), and more
• Sandbox pricing and limits: Active CPU, provisioned memory, and the limits