Concepts

Backups & snapshots

Two different things. snap is fast and in-place. backup uploads to R2.

`sb snap` — on-host snapshot

Fast in-place checkpoint of VM RAM + dirty blocks. Not uploaded. Lives only on the host that's running the sandbox.

froglet sb snap demo --label checkpoint

Use it when you want to try something risky and roll back in seconds. Lost if the host dies.

`sb backup` — R2-backed

Full snapshot uploaded to R2. Survives host loss. Restoring drops the sandbox back to the exact instant the backup was taken (RAM + disk).

$ froglet sb backup demo --label pre-experiment
✓ backup queued · 7054919a
  size  89.0 MB
  uri   r2://froglet-volumes/backups/fb7e61a0-…/7054919a-….tar.zst

List backups for a sandbox:

froglet sb backups demo

Restore

$ froglet sb restore demo --from 7054919a-…
✓ restore queued · f2a05926 · in_progress

Restore is a job — poll sandboxes.listRestoreJobs(sb.id) from the SDK to track. On completion, the sandbox is at the snapshotted state.

Backup policy

Per-sandbox automatic R2 backups, set via the SDK:

await sb.setBackupPolicy({
  enabled: true,
  intervalMinutes: 60,
  retainCount: 3,
  retainDays: 7,
  storage: 'r2',
});

retainCount and retainDays together gate pruning — a backup is kept while it satisfies either constraint.

Errors

422 backup_failed — pipeline rejected the request. Common cause: host being evicted.
sb stop can exceed 60s because the host takes an auto-snapshot before suspending — bump the SDK's timeoutMs for hot sandboxes.

CLI / SDK

CLI · sandboxes — snapshots & backups; SDK methods sandboxes.snapshot, sandboxes.backup, sandboxes.listBackups, sandboxes.restore, sandboxes.listRestoreJobs, sandboxes.getBackupPolicy, sandboxes.setBackupPolicy.

sb snap — on-host snapshot

sb backup — R2-backed