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 disk state of the box at the time of the snapshot, including cloned repos and installed packages.
Box configuration: the agent model, runtime, and browser setting. The agent harness is taken from the source box.

A restored box does not inherit:

Agent API key: a key passed directly as apiKey is not stored in the snapshot. The restored box uses your stored key for that provider or the Upstash-managed key. Pass agent again to use your own key.
Network policy: pass networkPolicy again on restore.
Attach headers: pass attachHeaders again on restore.
Lifecycle settings: init command, keep-alive, and size use the values passed on restore.
Schedules: active schedules are not carried over.

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: "3f9c2a1e-7b4d-4c8e-9a51-2d6f0b8e4c17",
//   name: "after-setup",
//   box_id: "sweet-shark-26021",
//   size_bytes: 52428800,
//   status: "ready",
//   created_at: 1771845600,
// }

snapshot = box.snapshot(name="after-setup")

print(snapshot)
# Snapshot(
#   id="3f9c2a1e-7b4d-4c8e-9a51-2d6f0b8e4c17",
#   name="after-setup",
#   box_id="sweet-shark-26021",
#   size_bytes=52428800,
#   status="ready",
#   created_at=1771845600,
# )

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: "3f9c2a1e-...", name: "after-setup", status: "ready", ... },
//   { id: "8b2e6d40-...", name: "pre-refactor", status: "ready", ... },
// ]

snapshots = box.list_snapshots()

print(snapshots)
# [
#   Snapshot(id="3f9c2a1e-...", name="after-setup", status="ready", ...),
#   Snapshot(id="8b2e6d40-...", name="pre-refactor", status="ready", ...),
# ]

Delete a snapshot

Remove a snapshot by ID.

await box.deleteSnapshot(snapshot.id)

box.delete_snapshot(snapshot.id)

Restore from a snapshot

Box.fromSnapshot() provisions a new box from the snapshot’s filesystem and agent model. 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("/workspace/home")
console.log(files)

restored = Box.from_snapshot(snapshot.id)

# Box.from_snapshot accepts creation options such as name:
named = Box.from_snapshot(snapshot.id, name="restored-worker")

files = restored.files.list("/workspace/home")
print(files)

The restored box starts with the same workspace state from the snapshot. Settings that are not inherited, such as agent.apiKey, networkPolicy, attachHeaders, initCommand, and keepAlive, can be passed to fromSnapshot(). Env vars from the source box carry over.

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: "https://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") {
  // 👇 the API key is not stored in the snapshot, so pass the agent again
  const fallback = await Box.fromSnapshot(checkpoint.id, {
    agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },
  })
  await fallback.agent.run({
    prompt: "Add connection pooling to the existing database layer without rewriting it",
  })
}

import os
from upstash_box import Box, Agent

box = Box.create(
    runtime="node",
    agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},
    git={"token": os.environ["GITHUB_TOKEN"]},
)

box.git.clone(repo="https://github.com/my-org/my-repo")
checkpoint = box.snapshot(name="pre-refactor")

run = box.agent.run(
    # 👇 Potentially difficult task
    prompt="Rewrite the database layer to use connection pooling",
)

if run.status == "failed":
    # 👇 the API key is not stored in the snapshot, so pass the agent again
    fallback = Box.from_snapshot(
        checkpoint.id,
        agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},
    )
    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) => {
    // 👇 the base box has no agent, so configure one on restore
    const box = await Box.fromSnapshot(baseSnap.id, {
      agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },
    })
    await box.agent.run({ prompt: task })
    return box
  })
)

import asyncio
import os
from upstash_box import Agent, AsyncBox

agent = {"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]}

async def main() -> None:
    base = await AsyncBox.create(runtime="node")
    await base.exec.command("npm install -g typescript eslint prettier")
    base_snap = await base.snapshot(name="node-toolchain")
    await base.delete()

    async def run_task(task: str) -> AsyncBox:
        # 👇 the base box has no agent, so configure one on restore
        box = await AsyncBox.from_snapshot(base_snap.id, agent=agent)
        await box.agent.run(prompt=task)
        return box

    # spawn boxes from the snapshot in parallel
    await asyncio.gather(*(run_task(t) for t in tasks))

asyncio.run(main())

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: "https://github.com/your-org/monorepo" })
const snap = await seed.snapshot({ name: "repo-cloned" })
await seed.delete()

// 👇 the seed box has no agent, so configure one on restore
const agent = { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY }

const [security, performance, docs] = await Promise.all([
  Box.fromSnapshot(snap.id, { agent }),
  Box.fromSnapshot(snap.id, { agent }),
  Box.fromSnapshot(snap.id, { agent }),
])

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" }),
])

import asyncio
import os
from upstash_box import Agent, AsyncBox

# the seed box has no agent, so configure one on restore
agent = {"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]}

async def main() -> None:
    seed = await AsyncBox.create(
        runtime="node",
        git={"token": os.environ["GITHUB_TOKEN"]},
    )
    await seed.git.clone(repo="https://github.com/your-org/monorepo")
    snap = await seed.snapshot(name="repo-cloned")
    await seed.delete()

    security, performance, docs = await asyncio.gather(
        AsyncBox.from_snapshot(snap.id, agent=agent),
        AsyncBox.from_snapshot(snap.id, agent=agent),
        AsyncBox.from_snapshot(snap.id, agent=agent),
    )

    await asyncio.gather(
        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"),
    )

asyncio.run(main())

​What’s included

​API

​Create a snapshot

​List snapshots

​Delete a snapshot

​Restore from a snapshot

​Examples

​Checkpoint before risky operations

​Reusable base environments

​Fan-out from a single state

What’s included

API

Create a snapshot

List snapshots

Delete a snapshot

Restore from a snapshot

Examples

Checkpoint before risky operations

Reusable base environments

Fan-out from a single state