Skip to content

Document why a checkpointed app can still cold start #346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Hkhan161 merged 1 commit into from
Sep 17, 2026
Merged

Document why a checkpointed app can still cold start #346

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions performance/checkpointing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,8 @@ After a successful save, the same endpoints report the size of the snapshot this

`checkpoint.size_bytes` is the snapshot this container saved; `restore.size_bytes` is the one it started from. A container does one or the other, so in practice only one block is present.

If a container starts with no `CEREBRIUM_RESTORED` marker after a checkpoint has been saved, see [When a restore does not happen](#when-a-restore-does-not-happen).

### 5. Disable checkpointing

A checkpoint is tightly coupled to a single deployment. To stop restoring from checkpoints, remove the POST request and redeploy the application.
Expand Down Expand Up @@ -161,6 +163,14 @@ engine.wake_up()

**Ephemeral filesystem:** Any files written to disk before the checkpoint are not copied to the restored container. Only memory is checkpointed.

## When a restore does not happen

A checkpoint is bound to the host machine environment it was captured on, which covers the host kernel, the CPU feature set, and the sandbox runtime version. A container restores only from a checkpoint captured in a matching environment.

An app can run across more than one compute pool in a region. A container that starts in a pool holding no matching checkpoint cold starts instead, then saves its own checkpoint when your app sends the trigger. Containers that later start in that pool restore from it, so each pool pays the cold start once.

Nothing is logged when a restore is skipped for this reason. The absence of the `CEREBRIUM_RESTORED` marker, or `"restored": false` from `GET /checkpoint/status`, is the only signal. An unexpected cold start after a successful checkpoint is normally this.

## Platform-specific recommendations

### vLLM
Expand Down
Loading