SMsmolmachines
checkpoints

Roll a machine back to a checkpoint.

Changed on

Replaces the machine's running state with one of its own checkpoints and starts it again. Unlike a restore, the machine keeps its id, name, network policy and credentials, so callers holding the id carry on as before. Work done since the checkpoint is discarded. The machine must have no live branches, since they share its running state.

post/v1/machines/{id}/rollback

Request

Path parameters

idstring required

Machine id

Request body

checkpointIdstring nullable

The checkpoint to return to. It must have been captured from this machine. Omitted means the machine's newest available checkpoint.

Response

Machine started from the checkpoint

archstring nullable

The machine's actual CPU arch (arm64/amd64): the arch of the node it runs on, falling back to source.arch (a .smolmachine's pinned arch) when the machine is unplaced or its node is gone. None only when neither is known. Lets the console show an arch badge for every machine, including ones whose source pinned no arch. Populated by the server's machine_info.

autoStopSecondsinteger nullable
branchGenerationinteger nullable

Zero for a root branch source, one for its children, and so on.

branchState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

branchableboolean

Whether this machine can produce live copy-on-write branches.

checkpointState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

createdAtstring required
createdBystring nullable

The account id of whoever created the machine; null when nobody is.

envobject required
ephemeralboolean required
errorstring nullable

When [Self::state] is "error", a human-readable reason the machine failed — the latest control-plane error event (e.g. "start failed: …", "auto-start failed: …", or "machine stuck in creating state"). null for machines that are not in an error state. Gives clients something actionable instead of a bare error with no explanation.

forkGenerationinteger nullable

Legacy alias for branch_generation.

forkableboolean

Legacy alias for branchable.

idstring required
labelsobject

Labels set at create time (or inherited from a branch source).

lastActivityAtstring nullable
namestring nullable
parentMachineIdstring nullable

Immediate live-RAM checkpoint this machine was branched from. null for ordinary machines and root checkpoints.

readyboolean

Whether the machine is READY to do work. state == "started" only means the VM process launched on the node — the guest OS and your in-VM workload still need a moment to boot. ready becomes true once the guest agent is reachable (an exec/connect will succeed) and, if the machine publishes a port, that port is accepting connections. Wait for ready (poll GET /v1/machines/:id) before expecting an in-guest worker to have started or before connecting to it — do NOT act on started alone.

readyAtstring nullable

When a probe first observed this machine serving (RFC3339), or null.

This is a readiness gate, not a boot timestamp: it is stamped when the published port accepts a connection (or, for a machine with no published ports, when its guest agent answers), and it is cleared on every stop so a restart must re-prove itself. A short-lived machine may finish its whole life as null here without anything being wrong. Use createdAt if you want when the machine came into existence.

rootBranchIdstring nullable

Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage.

rootCheckpointIdstring nullable

Legacy alias for root_branch_id.

statestring required
ttlSecondsinteger nullable
updatedAtstring required
urlstring nullable

Public ingress URL for the machine's first published port, when the machine is started and the control plane has a public base URL configured. null for stopped machines, machines with no published port, or when the deployment exposes no public base URL.

workdirstring nullable

Changes