How to use the Machine Checkpoint and Branch agent skill

What does the skill make the agent do?

smolvm has no scheduler and no retention of its own. The skill fills that gap: it runs a capture on a timer, keeps only the checkpoints you ask for, and lets the agent restore any generation in that history.

A restore is meant to bring back both the disk and the memory of the machine, so running processes can continue. The skill's own check for this is a workload that writes a counter into RAM and a marker to disk, then confirms both return after a restore.

The skill uses bundled shell scripts for each step and checks the results before reporting success. It is not meant for moving an environment to another host as a file, or for state that only has to survive a stop and start.

Install the skill from the ZIP or the Claude apps

Download the skill ZIP from this page. You can then install it in one of two ways.

For Claude Code, unzip it into your user skills folder ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for that project only.

In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

• User-wide: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Check what you need before you start

The skill requires smolvm and a bash shell. The source lists tested builds on macOS arm64 and Linux aarch64, so check your smolvm version against those hosts before relying on the skill.

On macOS, machines must be started with --branchable for capture and branching. Linux checkpoints and pauses work without it. The skill's scripts always start machines with this flag.

The skill runs scripts and does not use the network.

Ask for it in natural requests

You do not need to name the scripts. Describe the outcome and the agent picks the procedure. The skill triggers when a machine's state has to survive the machine, when an agent or job needs to roll back, when checkpoints must be taken periodically, when a prepared machine must be fanned out into workers, or when a checkpoint, pause or branch fails with an unclear error.

Useful requests name the machine, how often to capture, and how many to keep. For example, you might ask the agent to checkpoint your worker machine every ten minutes and keep the last two, or to restore yesterday's good checkpoint into a new machine so you can compare it with the current one.

• Checkpoint my worker machine every 10 minutes and keep the last 2.
• Roll back my agent's machine to the checkpoint from before the last run.
• Branch this prepared machine into 4 workers, each starting from the same point.
• Pause the machine now and resume it later with its processes still running.

Understand the procedure the agent follows

The agent works through a fixed sequence: a read-only preflight check, a source machine with state it can verify, capture (once or on a schedule), restore of any generation, pause and resume, branch points, and finally cleanup.

Capture is judged published only when the checkpoint log lists it as the current checkpoint. Only then does the skill delete the oldest checkpoints beyond the keep count. Set the schedule interval from the longest capture time reported, not from the pause, because the pause is short and the capture takes longer.

Keep count alone does not bound disk use. Each kept checkpoint also retains earlier history generations, so set both the keep count and the history depth.

• Preflight: reports whether the store has enough space and confirms the scheduler and retention are the skill's own.
• Restore: ~0 is the checkpoint itself and ~N is N generations back.
• Restores use machine create --from. There is no machine restore command.
• Restored machines take their own name as hostname.

Safety: scripts, sensitive data and cleanup

The skill runs scripts. Read them before you run them on a machine that matters. The skill does not use the network.

Checkpoints hold sensitive memory and disk contents. Treat them as confidential, and do not rely on unattended production schedules without review.

The cleanup script can kill VM processes when run with --reap. Only use that flag when you are sure which machines it will affect. Restores under names not starting with smolskill- are refused, so cleanup can find the machines it created.

• Captures refuse machines with host mounts, published sockets, remote volumes, host secrets, custom DNS, named networks, GPUs, CUDA, Rosetta, ssh-agent or a Docker socket.
• A full disk blocks capture. A machine restored while the disk was full may have guest I/O errors.
• Checkpoints that include host mounts restore only on a host where the same paths exist.

Tips for reliable checkpoints

Run the preflight script first, and stop if the store reports no free space. Create a test source machine if you want to see a restore bring back a counter and a file before you trust it with real work.

If a capture fails on macOS with an error about file-backed guest RAM, the machine was probably started without --branchable. Restarting it with the flag loses anything in RAM or /tmp once, so tell the user before doing it.

Keep schedules to minutes for real work. The short intervals in the examples are for watching the skill run.

• Run preflight before any capture.
• Bound both --keep and --history.
• Use --out only with a directory on the same filesystem as the store.
• Expect pauses of a few hundredths of a second, with captures taking seconds.