Devbox Snapshots - Runloop AI Docs

Start with the Runloop Quickstart to use the examples below.

Snapshots can be used to save the current disk state of a Devbox, and to create new Devboxes from a previously saved state. Snapshots can be used to:

Improve build times by snapshotting a populated build cache.
Roll back to a known good point in time.
Perform fan-out and attempt multiple approaches to a code change.

Snapshots are assigned a random identifier upon creation and can be queried via the API. Currently only disk snapshots are supported.

When should I use a Blueprint vs. a Snapshot?Snapshots and Blueprints both allow you to run devboxes with customizations. Blueprints are built programmatically and are cacheable using Docker layers, while Snapshots can be created quickly from an existing devbox.Examples:

Blueprint: You have a coding agent that is performing a task that requires installing a specific tool. Create a Blueprint with set-up steps for the tool. All Devboxes you launch from that Blueprint will have the environment already set up, and will not incur installation or setup time.
Snapshot: You have a coding agent in a devbox considering 3 different ways to complete a task. Create a snapshot of the initial state of the devbox, create 3 parallel devboxes from that snapshot, collate the results, and then choose the best option to continue.

Create a devbox to snapshot

Create a devbox with state to snapshot.

devbox = await runloop.devbox.create()
devbox.cmd.exec("echo 'Hello, World!' > hello.txt")            

const devbox = await runloop.devbox.create();
await devbox.cmd.exec("echo 'Hello, World!' > hello.txt");

Create a Snapshot

Start a Snapshot and wait for it to be ready.

snapshot = await devbox.snapshot_disk()
print(f"Snapshot operation completed with ID: {snapshot.id}")

const snapshot = await devbox.snapshotDisk();
console.log(`Snapshot operation completed with ID: ${snapshot.id}`);

Create a new devbox from the completed snapshot

Once the snapshot is complete, use the snapshot ID to launch a new devbox:

devbox = await snapshot.createDevbox()
const contents = await devbox.file.read("hello.txt")
print(f"hello.txt contents: {contents}")

const devbox = await snapshot.createDevbox();
const contents = await devbox.file.read("hello.txt");
console.log(`hello.txt contents: ${contents}`);

Asynchronous Disk Snapshots

When creating a disk snapshot you may want access to the Snapshot ID while you are waiting for the actual snapshot operation to complete. The asynchronous version of the snapshot operation allows this.

snapshot = await devbox.snapshot_disk_async()
print(f"Snapshot operation started with ID: {snapshot.id}")

await snapshot.await_completion()
print(f"Snapshot operation completed with ID: {snapshot.id}")           

const snapshot = await devbox.snapshotDiskAsync();
console.log(`Snapshot operation started with ID: ${snapshot.id}`);

await snapshot.awaitCompletion();
console.log(`Snapshot operation completed with ID: ${snapshot.id}`);

Deleting Snapshots

By default, snapshots persist indefinitely and continue to incur storage costs. To optimize resource usage and costs, you can delete snapshots that are no longer needed.

Deleting a Single Snapshot

To delete a specific snapshot simply:

await snapshot.delete()

await snapshot.delete();

Cleaning Up Old Snapshots for a Devbox

When you create multiple snapshots of the same devbox, you may want to delete older snapshots to reduce storage costs. Here’s how to keep only the latest snapshot for a specific devbox:

# Create a new snapshot
new_snapshot = await devbox.snapshot_disk(devbox.id)

# Get all snapshots for this devbox
snapshot_results = await runloop.snapshot.list(
  devbox_id=devbox.id
)

# Delete all older snapshots, keeping only the newest one
for snapshot in snapshot_results:
    if snapshot.id != new_snapshot.id:
        await snapshot.delete()
        print(f"Deleted old snapshot: {snapshot.id}")

// Create a new snapshot
const newSnapshot = await devbox.snapshotDisk(devbox.id);

// Get all snapshots for this devbox
const snapshotResults = await runloop.snapshot.list({
  devbox_id: devbox.id
});
// Delete all older snapshots, keeping only the newest one
for (const snapshot of snapshotResults) {
  if (snapshot.id !== newSnapshot.id) {
    await snapshot.delete();
    console.log(`Deleted old snapshot: ${snapshot.id}`);
  }
}

Be careful when deleting snapshots, as this action cannot be undone. Ensure you’re not deleting snapshots that you may need for rollback or recovery purposes.

​Asynchronous Disk Snapshots

​Deleting Snapshots

​Deleting a Single Snapshot

​Cleaning Up Old Snapshots for a Devbox

Asynchronous Disk Snapshots

Deleting Snapshots

Deleting a Single Snapshot

Cleaning Up Old Snapshots for a Devbox