Checkpoints

A checkpoint captures the full state of an instance—its memory and volume state—at any moment, so you can later start new instances that resume from exactly that state. Unlike a branch, which creates a single independent copy right away, a checkpoint is a reusable, named restore point that you can load as many times as you like.

You can take a checkpoint of a running instance without stopping it, keep a history of successive checkpoints, and create new instances from any checkpoint later on.

How it works

Checkpointing builds on the same machinery as branching. When you create a checkpoint, Unikraft Cloud:

1. Branches the source instance using copy-on-write (CoW) asynchronous snapshotting. Because the snapshot is copy-on-write and taken asynchronously, the source instance only pauses for a few milliseconds before it resumes running.
2. Converts the resulting branch into an instance template and marks it as a checkpoint.

This means checkpoints reuse the entire template lifecycle—storage, cloning, autokill, tags, and delete locks—but with their own dedicated endpoints.

A freshly created checkpoint starts in the starting state while the platform is still building its snapshot. Once the snapshot completes and the checkpoint becomes ready, it transitions to the checkpoint state. You can only load a checkpoint once it reaches the checkpoint state.

Creating a checkpoint

To create a checkpoint, pass the source instance to unikraft instance checkpoint create:

Code
unikraft instance checkpoint create my-instance

The CLI doesn't name the checkpoint, so the platform derives a name from the source instance's name plus a random suffix.

Checkpoint creation is asynchronous, so the new checkpoint reports starting until its snapshot completes. Either wait for it afterward, or have the create call wait for you:

Code
# wait for an existing checkpoint to become ready
unikraft instance checkpoint wait my-checkpoint --until state==checkpoint

# or wait during creation, for up to 60 seconds
unikraft instance checkpoint create my-instance --set wait-timeout=60s

To choose the name yourself, call POST /instances/checkpoints directly—the CLI doesn't cover it:

Code
unikraft api /v1/instances/checkpoints \
  '{
    "name": "my-checkpoint",
    "from": {
      "name": "my-instance"
    }
  }'

To take checkpoints on a recurring schedule rather than on demand, give the instance a checkpoint scheduled operation.

Checkpoint history

Every instance keeps an ordered history of its checkpoints, spanning the full lineage rather than only the checkpoints taken directly from that instance. When you create an instance from a checkpoint and then take further checkpoints from that instance, its history includes the new checkpoints and the ones inherited from the parent checkpoint.

For example, given this sequence:

1. Create inst1.
2. Create chk1 from inst1.
3. Create inst2 from chk1.
4. Create chk2 from inst2.

The history of inst2 lists both chk2 (taken directly from inst2) and chk1 (inherited from the checkpoint inst2 was loaded from).

To query this history, run unikraft instance history:

Code
unikraft instance history my-instance

Code
METRO  TARGET           NAME                 CREATED
fra    fra/my-instance  my-other-checkpoint  2 minutes ago
fra    fra/my-instance  my-checkpoint        4 minutes ago

The checkpoints themselves also carry this history of their lineage. You can query it directly with unikraft instance checkpoint history, which returns the same shape:

Code
unikraft instance checkpoint history my-checkpoint

Checkpoint information

To retrieve detailed information about a checkpoint, including its instance configuration, and volumes, query it by name or UUID:

Code
unikraft instance checkpoint get my-checkpoint

List all available checkpoints by omitting the identifier:

Code
unikraft instance checkpoint list

Code
METRO  NAME           STATE       IMAGE  ARGS  MEMORY  VCPUS  CREATED
fra    my-checkpoint  checkpoint  nginx        256MiB  2      4 minutes ago

Loading a checkpoint

You load a checkpoint by creating a new instance from it. Pass the checkpoint to --checkpoint:

Code
unikraft instance create --metro fra \
  --name my-new-instance \
  --checkpoint my-checkpoint

Use unikraft run --checkpoint instead to load the checkpoint and follow the new instance's logs in one step.

The new instance inherits the image, vCPUs, memory, arguments, environment, and saved memory and volume state from the checkpoint. As with branching and instance templates, you can configure the remaining properties—the instance name, volumes, ROMs, and services.

The checkpoint must be ready (in the checkpoint state) before you can load it. Loading a checkpoint that's still in the starting state fails (see Error handling).

Autokill

Like instance templates, checkpoints persist on the machine once created, holding onto the storage their snapshot occupies. A checkpoint can carry an autokill policy that removes it automatically when nothing loads it for a configured time, measured from the last load.

Set the policy with --autokill when you create the checkpoint:

Code
unikraft instance checkpoint create my-instance --autokill time=1h

You can also set or update the policy on an existing checkpoint:

Code
unikraft instance checkpoint edit my-checkpoint --autokill time=1h

This example removes the checkpoint after 1 hour without a load. unikraft instance checkpoint get reports the policy as autokill.time.

Editing a checkpoint

Use unikraft instance checkpoint edit to update a checkpoint's tags, delete lock, and autokill policy:

Code
# add a tag, keeping the existing ones
unikraft instance checkpoint edit my-checkpoint --add tags=my-new-tag

# replace the tags outright
unikraft instance checkpoint edit my-checkpoint --tag my-only-tag

# protect the checkpoint from deletion
unikraft instance checkpoint edit my-checkpoint --delete-lock

Deleting a checkpoint

Delete a checkpoint by name or UUID:

Code
unikraft instance checkpoint delete my-checkpoint

Code
unikraft instance checkpoint edit my-checkpoint --set delete-lock=false

Deleting the instance that owns a set of checkpoints doesn't remove the checkpoints. They remain available to load until you delete them explicitly or their autokill policy removes them.

Error handling

The CLI rejects a checkpoint in a different metro from the new instance before it sends anything, with cannot create instance: metro mismatch between checkpoint ("fra") and instance ("dal2"). Otherwise, a checkpoint request can fail for the following reasons:

Limitations

• A checkpoint and the instances you load from it must stay in the same metro. The CLI catches a cross-metro checkpoint before it sends the request.
• Checkpointing needs the default micro instance type. QEMU-backed full VMs (type: full), which GPU instances require, don't support checkpointing, and a create request can't combine type with a checkpoint source.
• Checkpointing builds on branching, so it only works with block-based volumes (for example, ext4). The checkpoint clones the source's volume state consistently with its memory snapshot, which isn't supported for other volume types.
• On BYOC and on-prem installations, checkpointing requires a license that includes the feature.

Learn more

• Branching: create a single independent copy of a running instance—the mechanism checkpoints build on.
• Instance templates: how templates work, the lifecycle checkpoints reuse.
• Autokill: automatically removing checkpoints and templates the platform hasn't loaded recently.
• Snapshots: the copy-on-write snapshotting that underpins checkpoints.
• Serverless databases: a use case that checkpoints a running PostgreSQL instance to capture and restore its state.
• Cron jobs / scheduled wake-ups: the checkpoint action periodically creates restore points for an instance.
• Unikraft Cloud's REST API reference, in particular the section on instances.