> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots and branching

> How sandbox state persists: immutable snapshots, one create-from verb, and recorded lineage.

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

```sh theme={null}
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

```sh theme={null}
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:

```sh theme={null}
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](/sandboxes/architecture#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](/sandboxes/overview) instead of baking data into
snapshots.

## Related pages

* [Sandbox lifecycle](/sandboxes/lifecycle): states, stop/start, TTLs.
* [Run a sandbox](/guides/running-sandboxes): the end-to-end flow these verbs live in.
* [Architecture](/concepts/architecture): where snapshots sit in the system.