From 35124b094e61f075326ae7d7d9597db829ab7386 Mon Sep 17 00:00:00 2001 From: Harris Khan Date: Thu, 17 Sep 2026 09:53:55 -0400 Subject: [PATCH] Explain the cold start that follows a restore with no match Co-authored-by: Cursor --- performance/checkpointing.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/performance/checkpointing.mdx b/performance/checkpointing.mdx index fb138fc1..63bae3b4 100644 --- a/performance/checkpointing.mdx +++ b/performance/checkpointing.mdx @@ -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. @@ -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