Snapshots - Upstash Documentation

Snapshots let you capture and duplicate box state. Use snapshots to save a point-in-time checkpoint you can restore later.

What's included#

A snapshot captures:

Filesystem: the full disk state of the box at the time of the snapshot.
Agent configuration: the agent harness, model, and API key settings.

A snapshot does not carry active schedules over to the new box.

Note

Snapshots are the best way to preserve cloned repositories, installed dependencies, and prepared workspaces. If your box already has a repo checked out, restoring from a snapshot is usually faster than cloning it again.

API#

Create a snapshot#

Call snapshot() on a running or paused box. The returned Snapshot object contains the ID you need to restore later.

const snapshot = await box.snapshot({ name: "after-setup" })console.log(snapshot)// {//   id: "snap_x7f...",//   name: "after-setup",//   boxId: "box_abc123",//   sizeBytes: 52428800,//   createdAt: "2026-02-23T..."// }

Note

Snapshots are independent of the source box. Deleting the original box does not delete its snapshots. They remain available for restore at any time.

List snapshots#

Retrieve all snapshots belonging to a box.

const snapshots = await box.listSnapshots()console.log(snapshots)// [//   { id: "snap_x7f...", name: "after-setup", status: "ready", ... },//   { id: "snap_a3b...", name: "pre-refactor", status: "ready", ... },// ]

Delete a snapshot#

Remove a snapshot by ID.

await box.deleteSnapshot("snap_x7f...")

Restore from a snapshot#

Box.fromSnapshot() provisions a new box with the exact state from the snapshot. The original box is unaffected. You can branch into multiple boxes from the same checkpoint.

const restored = await Box.fromSnapshot(snapshot.id)// Box.fromSnapshot accepts creation options such as name:const named = await Box.fromSnapshot(snapshot.id, { name: "restored-worker" })const files = await restored.files.list("/work")console.log(files)

The restored box starts with the same workspace state from the snapshot. You can also configure lifecycle settings such as keep-alive and init commands on the restored box.

Examples#

Checkpoint before risky operations#

Snapshot your working state, then let the agent attempt a large refactor. If the result is bad, we restore the original state and try a different prompt.

import { Agent, Box } from "@upstash/box"const box = await Box.create({  runtime: "node",  agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },  git: { token: process.env.GITHUB_TOKEN },})await box.git.clone({ repo: "github.com/my-org/my-repo" })const checkpoint = await box.snapshot({ name: "pre-refactor" })const run = await box.agent.run({  // 👇 Potentially difficult task  prompt: "Rewrite the database layer to use connection pooling",})if (run.status === "failed") {  const fallback = await Box.fromSnapshot(checkpoint.id)  await fallback.agent.run({    prompt: "Add connection pooling to the existing database layer without rewriting it",  })}

Reusable base environments#

Install dependencies once, snapshot, then spawn boxes from the snapshot to skip setup time.

import { Agent, Box } from "@upstash/box"const base = await Box.create({ runtime: "node" })await base.exec.command("npm install -g typescript eslint prettier")const baseSnap = await base.snapshot({ name: "node-toolchain" })await base.delete()const boxes = await Promise.all(  tasks.map(async (task) => {    const box = await Box.fromSnapshot(baseSnap.id)    await box.agent.run({ prompt: task })    return box  }))

Fan-out from a single state#

Clone a repo once, snapshot, then run different agents or prompts in parallel from the same starting point.

import { Agent, Box } from "@upstash/box"const seed = await Box.create({  runtime: "node",  git: { token: process.env.GITHUB_TOKEN },})await seed.git.clone({ repo: "github.com/your-org/monorepo" })const snap = await seed.snapshot({ name: "repo-cloned" })await seed.delete()const [security, performance, docs] = await Promise.all([  Box.fromSnapshot(snap.id),  Box.fromSnapshot(snap.id),  Box.fromSnapshot(snap.id),])await Promise.all([  security.agent.run({ prompt: "Audit src/ for SQL injection vulnerabilities" }),  performance.agent.run({ prompt: "Profile the hot paths in src/api/ and optimize" }),  docs.agent.run({ prompt: "Generate API documentation for all public exports" }),])