Snapshots and branching

A sandbox’s runtime is disposable; a snapshot is the part you keep. Snapshotting captures a sandbox’s disk state as an immutable resource, and hiloop sandbox create --from <snapshot> boots a new sandbox from it. That one verb is restore, fork, and branch: one child resumes work, several children explore alternatives from an identical starting point.

The model

Term	Meaning
Snapshot	An immutable capture of one sandbox’s disk state, created from a `ready`, `running`, or `stopped` sandbox.
Durability	What a snapshot receipt has proven: `local` (the storage snapshot exists) or `replicated` (its remote upload is confirmed).
Lineage	The recorded ancestry: each snapshot names its source sandbox and parent snapshot, and each branched sandbox appends its id to its parent snapshot’s lineage path.

Three properties do the work:

Disk, not memory. A snapshot captures the filesystem. Processes and memory never survive; checkpoint durable work as files before snapshotting.
Truthful durability. A receipt reports exactly what has been proven, local or replicated, rather than holding your request until replication completes; pass --wait-remote to wait (bounded at 25 seconds) for confirmed replication.
No hidden snapshots. Persistence is explicit. Nothing is captured unless you ask; deleting a sandbox destroys its runtime state, while snapshots you created outlive it.

Snapshot

hiloop sandbox snapshot create experiment-a --name baseline --wait-remote
hiloop sandbox snapshot list --sandbox experiment-a
hiloop sandbox snapshot delete baseline

One snapshot per sandbox is in flight at a time (a concurrent request returns 409 snapshot_in_progress), retries are replay-safe with --idempotency-key, and a snapshot still needed by a live restore refuses deletion with 409 snapshot_in_use.

Branch

hiloop sandbox create arm-1 --from baseline
hiloop sandbox create arm-2 --from baseline
hiloop sandbox create arm-3 --from baseline

Each child is an independent sandbox starting from identical bytes. Fan-out is the intended use: prepare an environment once, snapshot it, and explore many paths concurrently. Because lineage is recorded on both snapshots and sandboxes, the ancestry of every branch survives in the record and can be listed after the fact:

hiloop sandbox snapshot list
hiloop sandbox get arm-2 --output json

There are no separate fork, restore, or resume verbs: creating from a snapshot is the single, deliberate spelling of all three.

What survives what

Event	Standard storage	Durable storage	Snapshots
Process exit	filesystem survives	filesystem survives	unaffected
Stop / start	comes back from the image	`/workspace` is presented again; the rest comes back from the image	unaffected
Node loss	may be lost since the last snapshot	`/workspace` survives; the rest comes back from the image	unaffected once `replicated`
Sandbox delete	destroyed	destroyed	unaffected
Snapshot delete	unaffected	unaffected	that snapshot only

Processes and memory are not resumed across a stop or a node loss on either storage class (a stop does capture the process tree as a recorded restore point, but a start does not replay it; see memory capture), so a program that must pick up where it left off has to rebuild that from what it wrote to disk. On the default standard class, snapshot anything you cannot afford to lose. For large shared inputs such as datasets and model caches, publish a volume instead of baking data into snapshots.

Sandbox lifecycle: states, stop/start, TTLs.
Run a sandbox: the end-to-end flow these verbs live in.
Architecture: where snapshots sit in the system.

​The model

​Snapshot

​Branch

​What survives what

​Related pages

The model

Snapshot

Branch

What survives what

Related pages