Skip to content

Fork & branch

When an agent is about to try something risky, I save a checkpoint first. Then I can branch the work without cloning a machine by hand. Everything here runs on your own host — a cheap Linux box or an Apple Silicon Mac — not a cluster.

Terminal window
bhatti snapshot create agent --name before-upgrade
bhatti exec agent -- ./try-the-upgrade.sh
# A new sandbox from the earlier state, leaving agent alone:
bhatti snapshot resume before-upgrade --name retry

The default memory snapshot captures RAM/CPU state, the root disk, attached-volume copies and network policy. A resumed copy continues the processes from the checkpoint. If you only need root-disk files and want the copy to boot fresh, use bhatti snapshot create agent --name before-upgrade-disk --type filesystem; it captures only the root disk, not attached volumes or the source’s network policy. Preserve volume data separately. The source continues running in both cases. A snapshot name is unique: another create using the same name returns 409 Conflict rather than overwriting it.

create --from forks a live sandbox, not a snapshot name. To branch from a named snapshot, use snapshot resume instead:

Terminal window
bhatti create --name agent-branch-a --from agent
bhatti create --name agent-branch-b --from agent
bhatti snapshot resume before-upgrade --name agent-branch-c
bhatti snapshot resume before-upgrade --name agent-branch-d

Live forks capture the source’s current state at each call, so concurrent work may have moved on between calls. Repeatedly resume one named snapshot when every branch needs the same starting point. bhatti create --from before-upgrade would look for a live sandbox with that name and return 404, not resume the snapshot.

Each new sandbox has its own ID and, if networked, a fresh network identity. A live fork inherits its source’s network policy: --net, --egress, --allow-host, --allow-cidr, and --allow-siblings cannot override it on create --from. Create-time --mount and --secret-grant cannot be combined with --from either. If the source has no NIC (the default), the fork has no NIC. See Networking and Credentials.

The cloned device set of a live fork or memory snapshot includes RAM/CPU state, root-disk changes, attached-volume copies and the source network policy. Volumes are re-attached at their saved mount points; writes to a branch’s copies do not mutate the source’s disks or volumes. A filesystem snapshot instead captures only the root disk and cold-boots a fresh guest, without attached volumes or the source’s network policy. Preserve volume data separately; running processes and temporary /tmp are not retained. Host-side state — remote TCP peers, files bound from host directories, or external services — is not independently cloned. Review any credentials in each branch.

Forks reuse an immutable base and copy-on-write disk layers; they do not eagerly duplicate a whole root image for each branch. They still cost CPU when running, guest memory as touched, disk for each branch’s changes and volume copies, and a sandbox slot. A v2.5.0 measurement on agni-02 (i9-9900K, KVM, unix socket, p50) put fork at 150 ms and an idle 512 MB sandbox at ~58 MB PSS; your hardware and workload will differ. Destroy finished branches to release their own state; a named checkpoint remains until you delete it.

For an off-host checkpoint rather than a local branch, export and import a snapshot. For stop and write durability, read Data & durability.