Instances
An instance is a persistent sandbox: a disk image, a configuration, a manifest of state. It is the durable object that survives across VM boots. The VM (the actual running Firecracker microVM) is layered on top — see VMs.
Lifecycle in one sentence: create an instance from a base image, start a VM on it, exec commands or open ports, then either stop the VM (instance state persists) or delete the instance entirely.
Lifecycle
POST /v1/instances— create from a base image or familyGET /v1/instances— listGET /v1/instances/:id— read onePATCH /v1/instances/:id— update metadataDELETE /v1/instances/:id— delete (releases R2 storage)POST /v1/instances/:id/fork— clone from current statePOST /v1/instances/:id/rollback— revert to a prior manifest version
What lives under an instance
Each of these is its own topic page with deeper docs:
- VM lifecycle —
/instances/:id/vm(start, stop, restart, flush) - Exec — run commands inside the sandbox
- Files — read, write, list paths in the VM filesystem
- SSH — open SSH sessions to a running VM
- Port forwards — expose VM ports publicly
- Checkpoints — named manifests you can roll back to
- Snapshots — full memory + disk captures for fast resume
Related
- Base images — what an instance is created from
- Profiles — reusable CPU / memory / disk presets