Snapshots, forks and templates

Captured disks, branched machines, and named starting states.

Three things stand on one mechanism — capturing a machine’s disk — and differ in what they are for.

What a capture holds

Files, installed software, and browser profile data — cookies, logins, extensions.

It holds no RAM and no live process state. Restoring boots the disk; it does not resume a session. A process that was running is not running afterwards, and a file that was open is closed. includes_memory is false on every snapshot, and it is a property of the substrate rather than a setting, so there is nothing to turn on.

Design for that. Write state to disk, not to a long-lived process.

Secrets are delivered to tmpfs and are deliberately not carried by a capture.

Snapshots

POST   /v1/snapshots                        capture a machine's disk
GET    /v1/snapshots                        list, filterable by machine and origin
GET    /v1/snapshots/{snapshot_id}
DELETE /v1/snapshots/{snapshot_id}
POST   /v1/machines/{machine_id}/restore    put a machine back onto one

const snap = await machine.snapshot({ name: "after-setup" });

The machine has to be running — a disk is captured from a live instance. The capture is asynchronous; the SDKs wait for it by default so what you get back is immediately restorable, and wait: false gives you the pending record to poll yourself.

States are pending, ready, error and deleting. origin says how it came about:

• manual — you asked for it
• stop — taken automatically when the machine stopped
• template — the capture behind a template

Deleting is newest-first

Captures of one machine form a chain in the order they were taken, and only the newest can be deleted. Removing an older one is refused with a conflict naming the snapshot in the way. That is a consequence of how the chain is stored, not a policy, so there is no flag to override it — delete forward.

Restoring

await machine.restore(snap.id);

The current disk is captured first, under the name “Before restore”, so the state being replaced stays recoverable. The machine then restarts: a running one comes back running, a stopped one boots into the restored disk next time it is started. Anything open on the machine is disconnected, and nobody may be holding the input lease when you call it — the SDKs release theirs first.

Forks

const branch = await machine.fork({ name: "branch-a" });

Without a snapshot id the current disk is captured first, which needs the machine running. With one, the fork stands on bytes that already exist — which is how you fan out several machines from a single capture without paying for the capture each time:

const base = await machine.snapshot({ name: "configured" });
const workers = await Promise.all(
  ["a", "b", "c"].map((n) => machine.fork({ snapshotId: base.id, name: `worker-${n}` })),
);

A fork comes back in creating, exactly like a create, so waitForDesktop() is what waits for a usable computer. Afterwards it owes the original nothing: deleting the parent leaves every fork running.

Templates

GET    /v1/templates
POST   /v1/templates
GET    /v1/templates/{template_id}
DELETE /v1/templates/{template_id}

A template is a snapshot with a name on it and an organization behind it — how a team agrees on what its standard box is.

const tpl = await machine.saveAsTemplate({ name: "research-box" });
const fresh = await client.machines.create({ template: tpl.id, size: "standard" });

saveAsTemplate is the usual way to make one, because a template almost always begins as a machine somebody set up by hand. client.templates.create also accepts a snapshotId — standing on bytes that already exist — or neither, which makes it a named image and size with no captured disk behind it.

States are building, ready and error. Creating from a template pins the image; the size is still the create call’s to choose.

Deleting a template leaves machines created from it running and keeps their disks: a machine copies the template’s bytes when it is created and owes it nothing afterwards.

Quotas and cost

Snapshots per machine and templates per organization are plan entitlements. Captured disk counts toward storage, metered in byte-seconds and billed per GB-month. See billing.