Snapshots & persistence
Snapshot, restore, clone, fork, and back up a sandbox. See what each operation keeps.
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 (
scrub_env,clear_tmp,clear_ssh_keys) wipe secrets before a snapshot goes into a clone or fork. - 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 $SBXcurl -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"The parent keeps running untouched. The fork cold-boots from disk. It does not carry memory or processes.
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 $SBXcurl -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
| Operation | You get | Use when |
|---|---|---|
stop / start | the same sandbox, memory and processes intact where possible | pause work, save compute |
archive | the same sandbox, restored on next start | stopped for days, keep it cheap |
backup → restore-from-backup | the same sandbox on a fresh host | host loss, disaster recovery |
snapshot → restore | the sandbox rolled back to a point in time | checkpoints, undo |
clone | a new sandbox from a snapshot | duplicate a prepared sandbox |
fork | a new sandbox beside the running parent | branch a live sandbox |
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 — data that moves between sandboxes without snapshots
- API reference — full request/response shapes