---
title: "Roll a machine back to a checkpoint."
method: POST
path: "/v1/machines/{id}/rollback"
tags: ["checkpoints"]
---

# Roll a machine back to a checkpoint.

`POST /v1/machines/{id}/rollback`

## Request

- Base URL: `https://api.smolmachines.com`
- URL: `https://api.smolmachines.com/v1/machines/{id}/rollback`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/smolmachines/apis/smolfleet-api/docs/v1/machines/:id/rollback/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `id` string, required

## Request body

- RollbackMachineRequest: Roll a machine back to one of its checkpoints, keeping its id and name.
  - `checkpointId` string, nullable: The checkpoint to return to. It must have been captured from this machine. Omitted means the machine's newest available checkpoint.

## Response `200`

Machine started from the checkpoint

- MachineInfo
  - `arch` string, 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`.
  - `autoStopSeconds` integer, nullable
  - `branchGeneration` integer, 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.
  - `branchable` boolean: Whether this machine can produce live copy-on-write branches.
  - `cacheDisk` MachineCacheDisk: The cache disk a machine runs with.
    - `cacheDiskId` string, required
    - `intoSlot` boolean: Put in a cache slot by a restore, which needs an engine that serves slots.
    - `mountPath` string, required
    - `slot` boolean: Attached unmounted, as a slot a restore can put another cache in.
    - `version` integer, required
  - `capabilities` MachineCapabilities: Dynamic machine operations for clients that must feature-detect instead of guessing from a server or engine version.
    - `branch` boolean, required
    - `branchBatch` boolean, required
    - `exec` boolean, required
    - `fork` boolean, required
    - `forkBatch` boolean, required
    - `maxBranchBatch` integer, required
    - `maxForkBatch` integer, required: Legacy alias for `max_branch_batch`.
    - `nestedBranch` boolean, required
    - `nestedFork` boolean, required
  - `checkpointState` 'mutable' | 'freezing' | 'frozen': User-visible state of a live-RAM checkpoint.
  - `createdAt` string, required
  - `createdBy` string, nullable: The account id of whoever created the machine; null when nobody is.
  - `env` object, required
  - `ephemeral` boolean, required
  - `error` string, 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.
  - `forkGeneration` integer, nullable: Legacy alias for `branch_generation`.
  - `forkable` boolean: Legacy alias for `branchable`.
  - `id` string, required
  - `labels` object: Labels set at create time (or inherited from a branch source).
  - `lastActivityAt` string, nullable
  - `name` string, nullable
  - `network` union, required
    - object: No outbound access for the guest. The image PULL runs in-guest too, so a `blocked` machine whose image isn't already node-cached CANNOT fetch it and its start fails on an unreachable registry — opt into this deliberately.
      - `mode` 'blocked', required
    - object: Unrestricted outbound access. This is the DEFAULT: it matches what the `smol` CLI already sends, and means a create that omits `network` (raw API/SDK) can pull remote images out of the box instead of failing the start on an unreachable registry. Tighten with `blocked`/`allowCidrs`.
      - `mode` 'open', required
    - object
      - `cidrs` string[]
      - `hosts` string[]
      - `mode` 'allowCidrs', required
  - `parentMachineId` string, nullable: Immediate live-RAM checkpoint this machine was branched from. `null` for ordinary machines and root checkpoints.
  - `ports` MachinePort[]: Published ports with their allocated node host ports.
    - `hostPort` integer, nullable: Node host port allocated at placement (read-only; ignored on create).
    - `port` integer, required: Guest port the workload listens on.
  - `ready` boolean: 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.
  - `readyAt` string, 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.
  - `resources` MachineResources, required
    - `cpus` integer
    - `diskDurability` 'full' | 'deferred': When a machine's guest disk writes must reach the node's physical disk.
    - `diskGb` integer, nullable
    - `memoryMb` integer
  - `rootBranchId` string, nullable: Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage.
  - `rootCheckpointId` string, nullable: Legacy alias for `root_branch_id`.
  - `source` union, required
    - object
      - `arch` string, nullable: Requested CPU arch ("arm64"/"amd64"). Optional: an OCI image is usually multi-arch (the node pulls its own variant), so `None` means "no constraint" — but a caller that NEEDS a specific arch (e.g. x86-only binaries inside) can pin placement with it. Was previously silently dropped by deserialization.
      - `reference` string, required
      - `type` 'image', required
    - object
      - `arch` string, nullable: Canonical CPU arch the packed artifact targets ("arm64"/"amd64"). A `.smolmachine` is single-arch, so this becomes a hard placement constraint. `None` (older clients) means "no arch constraint".
      - `reference` string, required
      - `type` 'smolmachine', required
  - `state` string, required
  - `ttlSeconds` integer, nullable
  - `updatedAt` string, required
  - `url` string, 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.
  - `workdir` string, nullable

## Other responses

- `401`: Missing or invalid API key
- `403`: Key lacks the required scope
- `404`: Not found
- `409`: No usable checkpoint, the machine is busy, or it has live branches
- `429`: Rate limited; retry after the Retry-After header
- `500`: Internal error
- `502`: The old machine could not be torn down or the checkpoint could not be restored

## Changes

- **2026-10-16** `bc31fc04a568`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smolmachines/apis/smolfleet-api/changes/v1/machines/:id/rollback/post.md)

---

[API](https://skmtc.dev/smolmachines/apis/smolfleet-api.md) - [All operations](https://skmtc.dev/smolmachines/apis/smolfleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smolmachines/apis/smolfleet-api/revisions/bc31fc04a568?raw)