Checkpoints & Rewind

A checkpoint is a restore point for a machine. Rewind returns the machine to one — without destroying it. This is the reversibility at the heart of Clundra.

Base URL: examples use $CLUNDRA_API as a placeholder for your Clundra API host.

What a checkpoint captures

A checkpoint captures the machine's state at a moment in time — a restore point you can return to later. Take one before anything risky: a migration, a dependency upgrade, an experiment you're not sure about.

Checkpoints are an immutable list. Creating a new one never overwrites an older one — every checkpoint you've taken stays available to rewind to or fork from.

curl -X POST $CLUNDRA_API/machines/$ID/checkpoints \
  -H "X-API-Key: gopt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "label": "before-migration" }'

The response returns a checkpointId. In the dashboard, click Checkpoint to do the same.

Labeling

The label field is optional but worth setting — it's how you'll recognize a checkpoint later (“before-migration”, “clean-install”, “known-good”). List a machine's checkpoints to see them:

curl $CLUNDRA_API/machines/$ID/checkpoints \
  -H "X-API-Key: gopt_live_..."

Each entry includes its id, label, parentId, and createdAt.

How rewind behaves

Rewind restores the machine's state from a checkpoint. The important part: the machine stays live. It's the same machine with the same id — its state is moved back to the checkpoint, and it keeps running. Rewind does not move the machine “into the past” and does not prune your other checkpoints; they all remain rewindable.

curl -X POST $CLUNDRA_API/machines/$ID/rewind \
  -H "X-API-Key: gopt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "checkpointId": "'$CPID'" }'

In the dashboard, click Rewind to on any checkpoint.

Deleting a checkpoint

You can delete a checkpoint you no longer need:

curl -X DELETE $CLUNDRA_API/machines/$ID/checkpoints/$CPID \
  -H "X-API-Key: gopt_live_..."

One rule: you can't delete the checkpoint the machine is currently running from — that returns a 409 conflict. Rewind to a different checkpoint first, then delete.

Limits

Machines with a mounted volume cannot checkpoint, rewind, or fork. Reversibility applies to volumeless machines. If a machine has a volume attached, these operations are rejected — keep machines you want to rewind volumeless.

Want a copy instead of a restore? See Fork — it branches a brand-new machine from a checkpoint and leaves the source untouched.