Snapshots

A snapshot saves the exact state of a running machine so you can come back to it later. Use one to rewind a machine to how it was, or to start a brand-new machine that opens straight into that saved state.

Snapshots work the same way for both VMs and sandboxes. They save you from repeating slow setup: prepare a machine once, install and configure everything, take a snapshot, then spin up as many ready-to-go copies as you need.

Take a snapshot

snapshot(name?) saves the machine's current state and gives you back a snapshot id. The machine keeps running the whole time, so you can save a checkpoint without interrupting your work.

const sbx = await sandboxes.create({ template: "base" })
await sbx.connect()

// Do some slow, one-time setup.
await sbx.commands.run("sh", {
  args: ["-c", "apt-get update && apt-get install -y build-essential"],
  onStdout: (d) => process.stdout.write(d),
})
await sbx.files.write("/opt/app/config.json", "{ ...}")

// Save this state. The sandbox stays running.
const snapId = await sbx.snapshot("after-setup")
console.log("snapshot:", snapId)

Rewind a machine

revert(snapshotId) rewinds the same machine back to a snapshot. Its id doesn't change, so anything that points at it keeps working. Handy for resetting to a clean starting point between test runs.

await sbx.revert(snapId) // same sandboxId, state rewound

Start a new machine from a snapshot

Pass fromSnapshot to create to start a fresh machine from a snapshot. Each copy is fully independent, so you can run many at once from one prepared starting point.

// Start 5 ready-to-go workers from the same prepared snapshot.
const workers = await Promise.all(
  Array.from({ length: 5 }, () =>
    sandboxes.create({ template: "base", fromSnapshot: snapId }),
  ),
)

Snapshot vs. pause

Both save your state, but they're for different things:

• Snapshot: a named save point you can rewind to or start new copies from later, while the machine keeps running.
• Pause (Stop in the console): parks the machine and saves its state. A paused machine won't be shut down for being idle, and it picks up right where it left off the next time you connect().

await sbx.pause()                    // park it; picks up where it left off
await sbx.resume()                   // wake the paused sandbox back up