Snapshots & persistence

A snapshot is a full copy of a sandbox disk at one point in time. Use snapshots to roll a sandbox back, clone it, fork it, or recover it. Manage snapshots in each sandbox's Snapshots tab in the dashboard or with the API below.

Take, list, restore, and delete snapshots

The sandbox must be running before you snapshot it. restore rolls the sandbox back. It uses the latest snapshot unless you pass an id.

import { Platinum } from "@platinum-dev/sdk";
const client = new Platinum({ url: process.env.PT_API_URL, token: process.env.PT_TOKEN });
const sbx = await client.sandboxes.connect("sbx_01K…");

const snap = await sbx.snapshot();
const snaps = await sbx.listSnapshots();
await sbx.restore({ snapshotId: snap.id });
await sbx.waitRunning();
await sbx.deleteSnapshot(snap.id);

from platinum import Platinum
client = Platinum(token="pt_live_…", api_url="https://api.platinum.dev")
sbx = client.sandboxes.connect("sbx_01K…")

snap = sbx.snapshot()
snaps = sbx.list_snapshots()
sbx.restore(snapshot_id=snap["id"])
sbx.wait_running()
sbx.delete_snapshot(snap["id"])

pt sandbox snapshot $SBX
pt sandbox snapshots $SBX
pt sandbox restore $SBX --snapshot snap_…
pt sandbox snapshot-rm $SBX snap_…

curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/snapshot" -H "Authorization: Bearer $PT_TOKEN"
curl "$PT_API_URL/v1/sandboxes/$SBX/snapshots" -H "Authorization: Bearer $PT_TOKEN"
curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/restore" -H "Authorization: Bearer $PT_TOKEN" \
  -d '{"snapshot_id": "snap_…"}'
curl -X DELETE "$PT_API_URL/v1/sandboxes/$SBX/snapshots/snap_…" -H "Authorization: Bearer $PT_TOKEN"

• A restore deletes files created after the snapshot. Files deleted after the snapshot come back.
• Scrub flags wipe secrets from the sandbox's disk before the snapshot is taken, so a clone of it never sees them. They change the running sandbox too.
  • scrub_env: ["KEY", …] removes those variables from /etc/pt-env and /etc/environment, and from s6's envdir when it is on disk. A clone boots without them.
  • clear_ssh_keys: true empties every user's authorized_keys and deletes their private keys (~/.ssh/id_* and any other file in .ssh holding a private key). Public keys, known_hosts and config stay.
  • clear_tmp: true empties /tmp and /var/tmp.
  • The snapshot fails instead of capturing a secret it could not remove.
  • A sandbox whose template predates the agent that can scrub gets 409 scrub_unsupported_agent: rebuild the template and snapshot a sandbox created from it. If the agent does not answer its capability probe, the answer is 503 scrub_unverifiable; retry.
• Each snapshot is a full disk copy. It stays until you delete it.

Clone or fork a sandbox

clone boots a new sandbox from one of this sandbox's snapshots. It uses the latest snapshot when you omit the id. fork takes a snapshot and clones it in one call.

Each fork reserves the parent's full cpu, ram, and disk. Capacity limits how far you can fan out.

const c = await sbx.clone({ snapshotId: snap.id });
const f = await sbx.fork();
const child = await client.sandboxes.connect(f.id);
await child.waitRunning();

c = sbx.clone(snapshot_id=snap["id"])
f = sbx.fork()
child = client.sandboxes.connect(f["id"])
child.wait_running()

pt sandbox clone $SBX --snapshot snap_…
pt sandbox fork $SBX

curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/clone" -H "Authorization: Bearer $PT_TOKEN" \
  -d '{"snapshot_id": "snap_…"}'
curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/fork" -H "Authorization: Bearer $PT_TOKEN" \
  -d '{}'

The parent keeps running untouched. The fork cold-boots from disk. It does not carry memory or processes.

Snapshots, clones, and forks cover the sandbox's own disk, not its volumes. A volume keeps its own history. clone and fork fail with volume_busy while the source has volumes mounted: detach them first, then attach them to the new sandbox.

Back up and restore from backup

backup copies a running sandbox's root filesystem off-host. It pauses the sandbox for the copy, then resumes it. The tar and upload run in the background.

restore-from-backup cold-boots the latest backup. Files as of the backup survive. Process state does not.

const b = await sbx.backup();
const r = await sbx.restoreFromBackup();

b = sbx.backup()
r = sbx.restore_from_backup()

pt sandbox backup $SBX
pt sandbox restore-from-backup $SBX

curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/backup" -H "Authorization: Bearer $PT_TOKEN"
curl -X POST "$PT_API_URL/v1/sandboxes/$SBX/restore-from-backup" -H "Authorization: Bearer $PT_TOKEN"

Backups run automatically every 60 minutes. Call backup yourself for a tighter cadence.

Compare what survives what

Only stop/start and archive keep memory and running processes. The other operations start from disk alone. Processes restart and /tmp does not survive.

See also

• Sandboxes — stop/start, archive, auto_archive_days, lifecycle states
• Templates — build routes, stateful capture, warm spawns
• Volumes — persistent, versioned disks shared across sandboxes
• API reference — full request/response shapes