Skip to content

Automatic persistence now in beta on Vercel Sandbox

Marc Codina Segura, , , ,
BlogChangelog

Vercel Sandboxes can now automatically save their filesystem state when stopped and restore it when resumed. This removes the need for manual snapshots, making it easier to run long-running, durable sandboxes that continue where you left off.

Link to headingHow it works

A sandbox is the durable identity, now identified by a name, its filesystem state, and configuration options. A session is the compute tied to that state, invoked as needed.

Automatic persistence introduces orchestration that separates storage from compute, reducing the need for manual snapshotting, so:

  • when you stop a sandbox, the session shuts down but the filesystem is automatically snapshotted.

  • when you resume, a new session boots from that snapshot. This state storage is not charged, so you pay when your setting is active.

import { Sandbox } from '@vercel/sandbox';
// Create a named sandbox
const sandbox = await Sandbox.create({ name: 'user-a-workspace' });
await sandbox.runCommand('npm', ['install']);
await sandbox.stop();
// Later, resume where you left off
const sandbox = await Sandbox.get({ name: 'user-a-workspace' });
await sandbox.runCommand('npm', ['run', 'dev']);

Persistence is enabled by default in the beta SDK, can be disabled between sessions with persistent: false. When disabled, the sandbox still exists after being stopped and can be resumed by its name, but each session starts with a clean filesystem.

If a sandbox is stopped and you run a command, the SDK will transparently create a new session, so you don't need to check state or manually restart

const sandbox = await Sandbox.create({ name: "long-lived-sandbox" });
await sandbox.writeFiles([{
  path: "run.sh",
  content: Buffer.from('#!/bin/bash\necho "Hello!"'),
  mode: 0o755,
}]);
// Days later
const resumedSandbox = await Sandbox.get({ name: "long-lived-sandbox" });
console.log(resumedSandbox.status); // stopped automatically
await resumedSandbox.runCommand("./run.sh"); // logs "Hello!"
console.log(resumedSandbox.status); // running

The beta SDK adds methods for managing sandboxes over their lifetime:

const sandbox = await Sandbox.get({ name: 'user-alice' });
// Scale up resources on a running sandbox
await sandbox.update({ resources: { vcpus: 4 } });
// Inspect session history and snapshots
const { sessions } = await sandbox.listSessions();
const { snapshots } = await sandbox.listSnapshots();
// Search across sandboxes
const { sandboxes } = await Sandbox.list({
  namePrefix: 'user-',
  sortBy: 'name',
});
// Permanently remove a sandbox and all its data
await sandbox.delete();

The beta CLI adds configuration management and session inspection:

  # Spin up a sandbox for a user
  sandbox create --name user-alice
  # User runs commands — if the sandbox timed out, it resumes automatically
  sandbox run --name user-alice -- npm test
  # Check what happened across sessions
  sandbox sessions list user-alice
  # Tune resources without recreating
  sandbox config vcpus user-alice 4
  sandbox config timeout user-alice 5h

This feature is in beta and requires upgrading to the beta SDK and CLI packages.

Install the beta packages to try persistent sandboxes today: pnpm install @vercel/sandbox@beta for the SDK, and pnpm install -g sandbox@beta for the CLI.

Persistent sandboxes are available in beta on all plans.

Learn more in the documentation.

Ready to deploy?

Start DeployingTalk to an Expert