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 (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.

// volumePolicy is required only when the source/snapshot has recorded attachments.
const c = await sbx.clone({ snapshotId: snap.id, volumePolicy: "omit" });
const f = await sbx.fork({ volumePolicy: "omit" });
const child = await client.sandboxes.connect(f.id);
await child.waitRunning();

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

pt sandbox clone $SBX --snapshot snap_… --volume-policy omit
pt sandbox fork $SBX --volume-policy omit

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

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

Volumes and snapshot policies

Sandbox snapshots and backups never copy attached volume contents. They record only {volume_id, type, mount_path, subpath, mode} attachment metadata.

• A same-sandbox restore replays recorded Shared Volume attachments from control-plane state. If the current mount set conflicts, detach the changed mount first; the restore fails explicitly rather than changing it silently.
• A backup restore replays Shared Volume attachments on its newly scheduled host. Read/write Shared mounts remain the same shared data: concurrent writes to one path are last-writer-wins, not transactional.
• Local Volume bytes are not included in sandbox snapshots or backups. Sandbox snapshot, clone, and fork with an attached Local Volume are rejected until a proven freeze/detach consistency mode exists. A sandbox backup records the attachment metadata, but restore returns an explicit unsupported-consistency error rather than moving or copying the host-local disk.
• clone and fork require volume_policy whenever the source has volume attachments: omit creates no child attachments; reattach reattaches only Shared Volumes and warns for rw; clone returns an explicit unsupported error until independent, consistent volume cloning is implemented.
• When there are no recorded attachments, omit volume_policy entirely; clone and fork stay a one-click/no-extra-flag operation.

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 — data that moves between sandboxes without snapshots
• API reference — full request/response shapes