Branches and checkpoints

A checkpoint is a named snapshot of a disk. It takes about 15 ms whatever the disk’s size, and never changes once taken. A branch is a writable copy of a disk started from a checkpoint, in about 35 ms. Writes on a branch never reach the disk or its other branches, so each agent, session or CI job can get a copy of its own.

Both sessions start from the checkpoint base. Each branch shares the seed's data until it writes, and its writes stay on that branch.

Seed a disk and checkpoint it

Archil.Checkpoint runs commands against the disk at deploy time, then takes the checkpoint in the same microVM, so it holds exactly what they produced:

src/workspace.ts

import * as Archil from "@alchemy.run/archil";
import * as Effect from "effect/Effect";

export const Seed = Archil.Disk("Seed", {});

export const Base = Effect.gen(function* () {
  const seed = yield* Seed;
  return yield* Archil.Checkpoint("Base", {
    disk: seed.diskId,
    name: "base",
    run: ["git clone --depth 1 https://github.com/acme/app repo"],
  });
});

Branch per session

Archil.BranchDisk gives a Worker or Lambda a client that creates branches while the app runs:

const seeds = yield* Archil.BranchDisk(Seed);
const branch = yield* seeds.branch({ name: "session-42", fromCheckpoint: "base" });

Mount it on your own host with MountDisk and branch: "session-42". Branches share the disk’s credentials, so a disk user that mounts the disk can mount any of its branches. A sandbox can’t mount a branch yet.

Declare a branch

A branch that lives as long as the Stack, like a staging copy, is a resource:

src/workspace.ts

export const Staging = Effect.gen(function* () {
  const seed = yield* Seed;
  const base = yield* Base;
  return yield* Archil.Branch("Staging", { disk: seed.diskId, fromCheckpoint: base.name });
});

Fork a sandbox

A sandbox’s root filesystem is a disk too, so fork uses the same checkpoint and branch to copy a sandbox in milliseconds. A sandbox with mounted disks has to be stopped first.

const copy = yield* sandbox.fork({ name: "task-1-retry" });

Deleting

Archil can’t delete checkpoints or branches yet. Destroying an Archil.Checkpoint or Archil.Branch removes it from Alchemy’s state only, and deleting the disk deletes them with it.