All pages
How it fits together
There is one primitive here, a machine, and everything else is a way of arranging machines. That is worth five minutes before the rest of these pages, because the words are used precisely.
A machine
A machine is a Firecracker microVM with its own kernel, its own network namespace, a root disk, and a permanent URL derived from its name. It runs a stock image with a shell, Node and Python, or an image built from your own code.
Two things about it are not what container experience predicts. Creating one is a RESTORE from a template rather than a boot, so the time it takes is independent of how much memory it has. Suspending one is a FREEZE rather than a kill: memory and disk are captured, every process resumes exactly where it was, and nothing of the machine stays resident on the host while it sleeps.
A service
A service is one or more machines behind a URL that never changes. The URL is minted when the service is created and a request to it reaches whatever machines the current release has, which is why a deploy can replace every replica without moving the address.
A deploy builds a root filesystem, cuts a release, starts a replica from it, and lets that release take traffic only once the replica has passed its health check. That gate is the reason a broken deploy does not take the working one down.
A sandbox and a production replica are the same object with different lifecycle knobs. Promote turns the first into the second without changing its URL, and nothing is copied or recreated on the way.
An app
An app is a group of services deployed together from one compose file. They
share a name and a private network: a service reaches a peer at
<name>.internal, which is why a database URL in a compose file points at a name
rather than at an address somebody has to fill in.
An organization
An organization owns machines, services, volumes and domains, and is what a
bill is addressed to. An API key belongs to one organization and sees nothing outside it,
so an object in another organization answers not_found rather than
forbidden. That is deliberate: the alternative tells a stranger that the name
they guessed exists.
The lifecycle, and what each step costs
| Step | What happens | What it costs while it lasts |
|---|---|---|
| create | A restore from a template, not a boot. The machine is running before most of it has been read. | The machine is awake and billed. |
| suspend | Memory and disk are captured and the machine leaves the host entirely. The default timer is 60s of quiet, and the ceiling on it is an hour. | Nothing. No process, no reserved memory, no interface. |
| wake | The next request, exec or attach brings it back with its processes running. A request that arrives while it sleeps is HELD, for up to 120s, rather than answered with an error page. | Awake again from the moment it resumes. |
| checkpoint | A named capture of the whole machine, memory included, that can be restored or forked later. | Storage in the bucket, and nothing else. |
| destroy | Irreversible, and it takes the machine’s checkpoints with it. | Nothing afterwards. |
Where state actually lives
Object storage is the truth for a machine's disk and for a volume alike. The host's own NVMe is a read-through cache in front of it, and the design test for that claim is blunt: wipe any host's disk and nothing is lost.
- A machine's root disk and its volume are one storage model, not two. There is no local copy that has to be migrated when a machine moves.
- A volume is in the bucket before a write is acknowledged. A root disk is flushed within a published window, 60s.
- Console logs are NOT state. They are bounded and rotated, and a host that is wiped loses them while every machine restores exactly as before.
Why no host matters
Every host runs the identical stack and serves the whole API from its own replica of the fleet's state. There is no scheduler tier, no managed database and no control plane to be down: a call about your machine works on a host that has never run it, and a suspended machine wakes wherever there is room.
The one seam worth knowing is the processor. A memory image carries raw
CPUID, so it is portable within a vendor pool and never across one. When no host of that
pool is live, a machine COLD-BOOTS from its own disk instead: the id, the name, the URL,
the volume and every byte on disk survive, and the processes that were running do not. The
machine reports last_start: cold_boot so you can tell which happened.
The architecture page is the long version, and the internals page is the longer one.