Skip to main content
Set up your tools and project once. Save a checkpoint, then create independent boxes with the same files and configuration. A checkpoint captures a stopped box’s disk and execution configuration. It does not preserve memory or running processes, and each restored box gets a new ID.

Create a checkpoint and restore two boxes

Create a project file, save it in a checkpoint, and restore it in a new box. Then change one copy and create another: the second starts from your saved baseline.

Before you start

Use a Cloud API key with permission to create and delete boxes. This walkthrough creates one source box, two workers, and one checkpoint. CLI: follow the steps below in the same terminal. Python or TypeScript: install your SDK below, then run the complete example. The SDK snippets in each step explain the corresponding part of that program.
Install the latest CLI and log in, pasting your Cloud API key at the prompt:
app names your saved context. Keep this Bash or Zsh terminal open for every step below.

1. Prepare your workspace

Create a box and write a project file containing baseline. In your own workflow, this is where you would install tools or prepare project files before saving them.
The final line should be:
Save the printed source ID. The example disables idle-stop and automatic deletion so the box stays available while you work. Clean up at the end; choose your production lifecycle settings before capturing your own box.

2. Save a checkpoint

Stop the source before capture, then wait for the checkpoint to become ready. Keep the source stopped until capture finishes.
Continue only when the status is stopped. If needed, repeat the inspect command. Then capture the box:
Repeat boxlite --context app checkpoint get "$CHECKPOINT" until state is ready. If it is failed, read error_reason and stop here.
Do not proceed until the checkpoint is ready. Save its printed ID: you can use it again from another session, even after deleting the source box.

3. Restore and verify your files

Create a new box using only the checkpoint. No image or configuration overrides are needed: the saved settings are inherited.
The new box prints baseline even though you never wrote that file into it. Its worker ID is different from the source ID.

4. Create an independent second copy

Change the first worker’s file to branch-a, then create a second worker from the same checkpoint. Read both files:
After the second worker ID, you should see:
The first worker contains your change. The second starts from the saved baseline: editing a worker does not change the checkpoint or other workers. Your checkpoint is still available. Keep it to create more workers, or remove the demo resources when you are done.

5. Clean up when you are done

Keep the checkpoint if you want to create more workers. When finished, remove the demo resources yourself; none of the examples delete them automatically. For the CLI walkthrough, the IDs are still in your shell variables:
For an SDK run, or after closing the terminal, use the printed IDs with the cleanup commands. The workers remain running until you stop or remove them.

Complete SDK examples

Run one of these programs after installing its dependencies above. It performs steps 1–4, prints each resource ID, and leaves the checkpoint and boxes available for you to explore. Run step 5 when you are done. If a run fails, keep the IDs already printed and inspect those resources before retrying.
Save as checkpoint_demo.py:
checkpoint_demo.py
Save as checkpoint_demo.ts:
checkpoint_demo.ts

Capture your own box

Finish writes and stop your application’s work before stopping the box. Check that its status is stopped; checkpoint creation does not stop it for you. Keep it stopped and available until the checkpoint reaches ready. A source box cannot have attached volumes or Secrets. Save reusable tools and project files in a box without those attachments. Files already written into its root disk are included in the checkpoint, so remove credentials you do not want copied before capture. You can give a checkpoint a memorable name:
Creation returns before capture finishes. Use the waiting loop from step 2, or query the checkpoint until it is ready: Names accept letters, digits, ., _, and -, start with a letter or digit, and have at most 128 characters. Omitting a name generates one. Get, create-from-checkpoint, and delete accept an ID or name.

Reuse a checkpoint in another session

Use its saved ID or name in BoxOptions(checkpoint=...), { checkpoint: ... }, or boxlite create --checkpoint .... An optional new box name is the only creation override. Do not also pass an image, resource settings, empty lists, or lifecycle defaults: restored boxes inherit the saved configuration, and overrides are rejected.

What is preserved?

Memory, running processes, and open connections are not preserved. A restored box has a new identity. Reconnect clients to that new box, and launch your application through its saved startup command or a new execution. Checkpoint restoration creates a new box; it does not roll back or replace an existing box. For ongoing data shared across boxes, use Volumes. For restarting the same box, see Box lifecycle.

List and inspect checkpoints

SDK and CLI list operations fetch all pages. CLI lists also support --format json, --format yaml, or --quiet for IDs only. Do not combine --quiet with --format.

Clean up

A ready checkpoint is independent of its source. Deleting the source does not delete the checkpoint; deleting the checkpoint does not delete boxes already restored from it. If you have closed the walkthrough session, replace the placeholders with the IDs it printed. Run these commands from a terminal logged into the app context:
For checkpoint deletion, force=True (Python), true (TypeScript), or --force (CLI) only ignores a missing checkpoint. It does not bypass an active capture or restore operation.

Troubleshooting

For differences from local snapshots and portable archives, see Cloud vs open source.