Sandbox persistence is now GA

Vercel Sandboxes now automatically save and restore filesystem state between sessions. Persistence is on by default, meaning no snapshots to manage or state to track manually.

Each sandbox has a durable, customizable name that acts as a unique reference in your project. You can create, retrieve, or resume a sandbox by name. Vercel spins sessions up and down automatically, without interrupting your workflow.

Link to headingCreate a persistent sandbox

When you call Sandbox.create(), persistence is enabled by default:

1
import { Sandbox } from "@vercel/sandbox";
2
// Filesystem is snapshotted automatically
3
const sandbox = await Sandbox.create({ name: "my-sandbox" }); 
4
await sandbox.runCommand("npm", ["install"]);
5
await sandbox.stop();

Each automatic snapshot consumes snapshot storage, which is billed separately from compute. For ephemeral workloads, opt out of persistence to minimize storage costs:

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

3
const sandbox = await Sandbox.create({ persistent: false });
4
// Or update an existing sandbox.
5
await sandbox.update({ persistent: false });

To opt out of persistence with the CLI, pass --non-persistent to sandbox create. Non-persistent sandboxes discard their filesystem when the session ends.

Link to headingResume a persistent sandbox

Resuming is automatic. Any call on a stopped sandbox, like runCommand() or writeFiles(), starts a new session from the most recent snapshot.

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

3
const resumedSandbox = await Sandbox.get({ name: "my-sandbox" });
4

5
// Automatically resumes the sandbox.
6
await resumedSandbox.runCommand("npm", ["test"]);

Link to headingOther improvements

• Sandbox.fork(): Create a new sandbox from an existing one

• Sandbox.getOrCreate(): Idempotent retrieve-or-create for long-lived sandboxes

• Sandbox.delete(): Permanently delete a sandbox

• Richer sandbox.stop(): Returns snapshot metadata plus active-CPU and network-transfer totals

• Lifecycle hooks: onCreate and onResume hooks for create, get, and getOrCreate

• Tags: Assign custom properties to sandboxes for multi-tenant tracking

Link to headingGet started

Upgrade to the latest version to create persistent sandboxes by default:

• pnpm install @vercel/sandbox@latest # SDK

• pnpm install -g sandbox@latest # CLI

Learn more about persistent sandboxes in the documentation.