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

# How it thinks

> Sandboxes, images and templates, runtimes, shapes, rest states, and the durability rules.

**Sandbox.** A microVM with its own kernel, filesystem and network, identified
by `vm_id` (UUID). Created from an image, a template, or a snapshot.

**Image / template.** Any OCI reference. A template is that image booted once
and checkpointed; creates restore the checkpoint instead of booting. First use
of an (image, shape) registers a build — `503 template building` until ready.

**Runtime.** `container` (default): the image's entrypoint is PID 1 with a
kernel of its own. `vm`: the image *is* the machine — systemd, Docker daemons
(experimental at launch).

**Shape.** `cpus` (default 2, launch max 4), `memory_mb` (default 1024,
128–8192), `disable_internet` (no egress). Snapshot/template creates take the
source's shape. Every sandbox gets a fixed 16 GiB sparse writable disk.

## Rest states

Cheapest to most durable (p50, measured 2026-09-04, default sandbox):

| call                          | cost                                                                                                        | vCPUs                                    | wake                          | survives node loss                                                     | use for                                                              |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `snapshot(leave_paused=True)` | \~50 ms (+ \~170 ms to restore)                                                                             | paused                                   | transparent, on the next call | the snapshot does, once `durable` (seconds)                            | checkpoint, then idle across a model call                            |
| `pause` / `resume`            | \~32 ms each                                                                                                | paused                                   | explicit `resume`             | no                                                                     | a deliberate hold you control (advanced)                             |
| `sleep`                       | \~30 ms                                                                                                     | paused                                   | transparent, on the next call | no                                                                     | idle reclamation                                                     |
| `fork` / `fork(n)`            | \~55–75 ms one child; `n=4` ≈ 120–150 ms for all four (one checkpoint, parallel restores, one shared layer) | running                                  | —                             | no                                                                     | fork an experiment at a decision point; `n` capped at 4 at launch    |
| `archive` / `unarchive`       | 2–7 s / \~1–2 s                                                                                             | freed; memory archived to object storage | explicit `unarchive`          | **yes**                                                                | done for a while; release running resources                          |
| `reboot`                      | \~1–2 s                                                                                                     | running                                  | —                             | no (disk kept; memory, processes, sessions and exposed listeners lost) | recover a wedged guest (fork bomb, hung kernel) without losing files |

`archive` is the one operation whose cost varies with what is in the sandbox
(it packs and uploads writable memory and disk); it is a teardown-and-keep, not
a suspend. **When in doubt, do nothing** — autosleep covers idle; `archive()`
covers "done for days".

## Durability rules

Survives delete: snapshots, exports. Survives node loss:
archived sandboxes, durable snapshots. Survives reboot: the writable disk.
Everything else is as durable as the node under it.