Skip to main content
A snapshot is a reusable saved state of a sandbox. It captures the sandbox filesystem and memory state, so a new sandbox can start from that point later with the setup work already done.
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.
Snapshots are available only in some regions.

What a snapshot contains

A snapshot captures the state of a running sandbox at a moment in time: the filesystem and the live memory state, including anything created at runtime. Snapshots are persistent and remain available after the source sandbox is deleted. Use snapshots to:
  • Prepare dependencies once and reuse them in later sandboxes.
  • Save a known-good state before running risky or expensive work.
  • Start multiple sandboxes from the same captured environment.
  • Keep a reusable state after the original sandbox is no longer needed.

Snapshots and templates

Snapshots and templates both start new sandboxes from a predefined point, but they differ in how that point is produced and what it captures. The three terms form a chain:

Create a snapshot and start a sandbox from it

The sandbox is paused while the snapshot is being created.
In the console, a snapshot is created with the row action Save as snapshot; see Manage sandboxes in the PPIO console.
1

Create the snapshot

Call create_snapshot() on a running sandbox after the state to preserve is in place.
2

Start a sandbox from the snapshot

Pass the snapshot ID to create(). The captured state is already present, so the setup work does not run again.

Full example

In the CLI example, <sandbox-id> is the ID of the sandbox to capture.

Create a snapshot by sandbox ID

A snapshot can be created without a sandbox handle by passing the sandbox ID to the same method on the namespace. In the examples, <sandbox-id> is the sandbox ID.

List snapshots

Call the method and page through the results. Each page is a list of SnapshotInfo.

Filter by source sandbox

Pass a sandbox ID to list only the snapshots created from that sandbox.

Delete a snapshot

Delete a snapshot by its ID. The call returns true if the snapshot was deleted, or false if no snapshot with that ID was found.
Deleting a snapshot is permanent. Sandboxes already created from it are unaffected, but no new sandbox can be created from it afterwards. Deleting a snapshot can fail while sandboxes created from it are running. Kill those sandboxes before deleting the snapshot.
In the examples, <snapshot-id> is the snapshot ID.
Last modified on November 19, 2026