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.- CLI
- Python
- TypeScript
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 containingbaseline. In your own workflow, this is where you would install tools or prepare project files before saving them.
- CLI
- Python
- TypeScript
2. Save a checkpoint
Stop the source before capture, then wait for the checkpoint to becomeready. Keep the source stopped until capture finishes.
- CLI
- Python
- TypeScript
stopped. If needed, repeat the inspect command. Then capture the box:boxlite --context app checkpoint get "$CHECKPOINT" until state is ready. If it is failed, read error_reason and stop here.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.- CLI
- Python
- TypeScript
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 tobranch-a, then create a second worker from the same checkpoint. Read both files:
- CLI
- Python
- TypeScript
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: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.Python: complete runnable example
Python: complete runnable example
Save as
checkpoint_demo.py:checkpoint_demo.py
TypeScript: complete runnable example
TypeScript: complete runnable example
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 isstopped; 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:
- Python
- TypeScript
- CLI
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 inBoxOptions(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
- Python
- TypeScript
- CLI
--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 theapp context:
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.

