Skip to main content
Branches and checkpoints are generally available in all AWS regions. Checkpoints and branching for bring your own bucket (BYOB) are available on Enterprise. See plan features.
Branches and checkpoints let you capture the state of an Archil disk at a moment in time and then explore alternative histories without disturbing the original. A checkpoint is a named, point-in-time snapshot of the filesystem state on a disk. The filesystem state a checkpoint references is immutable. A branch is an independent, writable fork of a disk that starts from a specific checkpoint. Writes on a branch don’t affect the source branch. A checkpoint takes about 15 ms and a branch about 35 ms, regardless of disk size. Forking a sandbox uses the same operations on the sandbox’s root disk. A sandbox with mounted disks must be stopped before forking. Branches form a tree. Every branch points back to the checkpoint on its parent it was forked from. Checkpoints, in turn, always belong to a specific branch (or to the root).
If you’re familiar with Git, Archil branches and checkpoints map fairly directly to Git branches and Git commits respectively.
For example: A timeline showing the root disk with checkpoints chk: x and chk: z, branch 1 forked from chk: x with its own checkpoint chk: y, and branch 2 forked from chk: z. A timeline showing the root disk with checkpoints chk: x and chk: z, branch 1 forked from chk: x with its own checkpoint chk: y, and branch 2 forked from chk: z. Here, the root has two checkpoints: x and z. Branch 1 was forked from x and branch 2 was forked from z. Any mutations to the filesystem state on the root after x would not appear in branch 1 and vice versa.

​
Working with checkpoints

Checkpoints are taken from a mounted disk and capture the filesystem state at the time the command runs:
Checkpoint names must be unique within the branch they’re taken on. Once created, the state a checkpoint points to never changes. To see the checkpoints available on a disk:
The list is rendered oldest-first, so the most recent checkpoint appears at the bottom.

​
Working with branches

Create a branch by naming the checkpoint you want it to fork from.
To use a branch, mount it with --branch:
A mounted branch behaves exactly like any other Archil disk. You can read, write, take additional checkpoints from it, and create further branches off of those checkpoints. Writes to a branch are isolated from its parent and from any sibling branches. Because each branch is fully independent, you can mount it on any client, including a different VM from the one using its parent. Two branches of the same disk can also be mounted on separate VMs at the same time. This makes branches a natural fit for fan-out workloads such as giving each agent or CI job its own writable fork.
A branch is not a security boundary. Credentials are scoped to the entire disk, including all of its branches and checkpoints. Anyone who can mount the disk can access every branch and checkpoint on it. To isolate untrusted workloads from each other (for example, one agent or tenant per fork), give each its own disk rather than relying on branches. See Disk Users.
Deleting individual branches and checkpoints is currently not supported. We’re actively working on this feature, and if you need access to it sooner, please email support@archil.com.
For the full set of CLI flags, see archil checkpoints and archil branches in the CLI reference. For a worked example, see Running parallel agent attempts from one starting state with copy-on-write branches.