Branch and Checkpoint
Saves running smolvm machines on a schedule and branches from checkpoints.
Install
npx skills add smol-machines/smolvm --skill branch-and-checkpoint -g -a claude-code -y- Repository
- smol-machines/smolvm6.9k
- Category
- DevOps
- Updated
- 3d ago
- License
- Apache-2.0
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- Yes, review before use
What it does
Saves a running smolvm machine as checkpoints on a schedule, keeps a bounded history, restores any generation in it, pauses and resumes machines without losing running processes, and branches a warm machine into children with a checkpoint of the exact point they started from. Use when a machine's state has to survive the machine; when an agent or a job needs to roll back; when checkpoints must be taken periodically, since smolvm has no scheduler or retention of its own; when fanning a prepared machine out into workers; or when a checkpoint, a pause or a branch fails with an error that names none of its preconditions. Do not use it to ship an environment to another host as a file, which is the pack packet, or for state that only has to survive a stop and start, which is the dev-env packet.
Checkpoints, restores, pauses and branches
Verified on smolvm v1.29.0 on macOS arm64, 2026-10-15, and on v1.18.2 on Linux aarch64, 2026-09-24. Done means a restore brings back both the disk and the memory you left, the schedule keeps exactly the checkpoints you asked for and no fewer, and every child of a branch starts from a state you still hold as a checkpoint after the children are gone. The Linux runs used the scripts of their date; this version's preflight and cleanup scripts ran on Linux aarch64 on v1.22.2 on 2026-10-03.
README.md says what each of these operations is. This file is how to run them, and the traps.
Three facts shape everything here.
- smolvm has no scheduler and no retention.
scripts/checkpoint.shis the one capture a timer runs, with the rules the engine asks a scheduler to follow built in;references/scheduling.mdputs it under cron, systemd or launchd. - A branch's captured state stays on this host and cannot be exported. So a branch point is paired with a checkpoint taken at the same moment, which is the copy you keep.
--branchableatstartdecides what a machine can do later. A branch source needs it on every host, and on macOS so does a stored capture, which is what the scripts here take; Linux checkpoints and pauses without it.README.mdhas the errors when it is missing. The scripts always start with it.
Procedure
- [ ] 1. preflight.sh read result= and store_space_ok=
- [ ] 2. create-source.sh a machine with state in RAM and on disk
- [ ] 3. checkpoint.sh / schedule.sh captures, with retention
- [ ] 4. restore.sh any generation, into a new machine
- [ ] 5. pause and resume the restored machine, or any branchable one
- [ ] 6. branch-point.sh children plus a checkpoint of where they started
- [ ] 7. cleanup.sh machines, checkpoints, and smolvm's restore cache
1. Preflight. Read-only.
