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.
Save a return point
Section titled “Save a return point”bhatti snapshot create agent --name before-upgradebhatti exec agent -- ./try-the-upgrade.sh# A new sandbox from the earlier state, leaving agent alone:bhatti snapshot resume before-upgrade --name retryThe 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.
Branch a running agent N ways
Section titled “Branch a running agent N ways”create --from forks a live sandbox, not a snapshot name. To branch
from a named snapshot, use snapshot resume instead:
bhatti create --name agent-branch-a --from agentbhatti create --name agent-branch-b --from agentbhatti snapshot resume before-upgrade --name agent-branch-cbhatti snapshot resume before-upgrade --name agent-branch-dLive 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.
Budget for branches
Section titled “Budget for branches”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.