> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# The microVM

Last updated 2 November 2026

> Machines are not open yet. These pages describe Machines as they will open; until then, a create answers [`region_not_offered`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

Read this when you want to know what runs your image: the virtual machine, the agent inside it, and how a wake boots it and a sleep stops it.

## The hosts

Machines run on arm64 metal hosts of their own, apart from the hosts that run Tonbo’s services, with one host always on in each region and more added as Machines wake. A host runs tonbo-node, Tonbo’s host agent, which starts and stops the virtual machines and pulls their images (see [Image pulls](https://tonbo.dev/docs/machines/internals/image-pulls.md)).

## The virtual machine

Each wake is one [Firecracker](https://github.com/firecracker-microvm/firecracker/blob/d9f9a57d96627d9308140e0764a95e998e5587ff/docs/design.md) microVM on [KVM](https://docs.kernel.org/virt/kvm/index.html), started under Firecracker’s [jailer](https://github.com/firecracker-microvm/firecracker/blob/d9f9a57d96627d9308140e0764a95e998e5587ff/docs/jailer.md) (see [Isolation claims](https://tonbo.dev/docs/machines/internals/isolation.md)); Firecracker’s documents live in its [repository](https://github.com/firecracker-microvm/firecracker). Its vCPUs share the host’s cores, and a host admits no more memory than it has, so no Machine’s memory is overcommitted; each is bounded by its [cgroup](https://docs.kernel.org/admin-guide/cgroup-v2.html).

## Its drives

- The tools drive, which holds tonbo-guest, the agent inside the virtual machine, at `/tonbo`.
- The image root: the image’s layers flattened into one [ext4](https://docs.kernel.org/filesystems/ext4/index.html) filesystem with 1 GiB free, a fresh copy at every boot.
- The scratch drive at `/scratch`, as large as the shape allows, allocated as it is written, and empty at every boot (see [Release, not suspend](https://tonbo.dev/docs/machines/internals/activations.md#suspend)).
- The Volume drive, when the Machine has a Volume: one more virtio-blk drive with ext4, mounted at the Volume’s path and served on the host by a per-Volume daemon in its own jail, which keeps the Volume’s blocks in the region’s chunk store.

## Boot

The guest kernel boots the tools drive. tonbo-guest switches into the image root, mounts `/run`, `/dev` and `/tmp`, writes the database token to `/run/tonbo` in memory, takes the Machine’s configuration from the host, and runs the image’s `Entrypoint` and `Cmd` as its `User`, as the [image configuration](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md) names them.

## Stop

A planned stop that releases the Machine sends the program [SIGTERM](https://man7.org/linux/man-pages/man7/signal.7.html), waits the stop grace, then kills it, and the host sends what the database still had to send, within 60 seconds (see [Database wiring](https://tonbo.dev/docs/machines/internals/database.md)). A program that exits on its own ends the wake as `exited`, and one that runs out of memory as `oom` (see [Stops and the drain](https://tonbo.dev/docs/machines/internals/activations.md#stops)).