Full example

Snapshots can be used to save the current disk state of a devbox, and to create new devboxes from a previous point in time. These 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 referenced by a random identifier 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 fast to boot and cacheable using Docker layers, while Snapshots are a bit slower on boot (reproducing each step taken in the devbox) but 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 and future devboxes will cache the installation to speed up boot and execution 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.
1

Identify the devbox to snapshot

First, identify a running devbox id using the dashboard or rl-cli.

$ rl devbox list --status=running

Optionally, you may want to remove any temporary files before proceeding to reduce the latency of snapshot operations.

2

Snapshot the disk of a currently running devbox

curl -X POST 'https://api.runloop.ai/v1/devboxes/{devbox_id}/snapshot_disk' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
3

Create a new devbox from a snapshot

Using the snapshot_id from the previous step, launch a new devbox.

curl -X POST 'https://api.runloop.ai/v1/devboxes' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "snapshot_id": <snapshot_id>
  }'