# Hyper v0.1.0 - Table of Contents

## Pages

- [README](readme.md)
- [gRPC interface](grpc.md)

- Cookbook
  - [Quick Start](quickstart.md)
  - [Intro](intro.md)
  - [Installation](install.md)
  - [Configuration](config.md)
  - [Architecture](architecture.md)

## Modules

- [Hyper](Hyper.md): `Hyper` is a distrubuted elixir virtual machine orchestrator.

- [Hyper.Cfg](Hyper.Cfg.md): The one place every Hyper configuration value is read.
- [Hyper.Cfg.Budget](Hyper.Cfg.Budget.md): This node's resource budget. Each field reads from `config.exs`
(`config :hyper, Hyper.Cfg.Budget, ...`, typically set via the operator
override file `/etc/hyper/config.exs`), then the `[budget]` table in
`/etc/hyper/config.toml`, then its built-in default. `Unit.*` quantities may
be given as Elixir terms in `config.exs` or as strings (`"4GiB"`, `"1GiBps"`)
in TOML.

- [Hyper.Cfg.Cluster](Hyper.Cfg.Cluster.md): BEAM cluster (Distributed Erlang) topology for Hyper. Set it in `config.exs`
via `config :hyper, Hyper.Cfg.Cluster, topologies: [...]` using
[libcluster](https://github.com/bitwalker/libcluster) topology syntax;
`Hyper.Application` forwards it straight to `Cluster.Supervisor`, which is what
Horde's `members: :auto` registries form over. `config.exs`-only because a
topology references strategy modules. The default — `[]` — is a single,
unclustered node.

- [Hyper.Cfg.Dirs](Hyper.Cfg.Dirs.md): The node's work directory and every directory derived from it.
- [Hyper.Cfg.Gc](Hyper.Cfg.Gc.md): Layer garbage collector tuning. Each field reads from `config.exs`
(`config :hyper, Hyper.Cfg.Gc, ...`), then the `[img.gc]` table, then its
default. Durations are `Unit.Time` — Elixir terms in `config.exs`, strings
(`"60s"`, `"1h"`) in TOML.

- [Hyper.Cfg.Grpc](Hyper.Cfg.Grpc.md): gRPC server configuration, read from application env into a struct
- [Hyper.Cfg.Img](Hyper.Cfg.Img.md): This node's image storage configuration: the device-mapper geometry behind the
read-only layer chain (dm-snapshot) and the per-VM writable layers (dm-thin).
- [Hyper.Cfg.Img.Db](Hyper.Cfg.Img.Db.md): Image-database (Ecto/Postgres) connection settings — `database`/`username`/
`password`/`hostname`. These are secrets, so they are read from `config.exs`
only (`config :hyper, Hyper.Cfg.Img.Db, ...`), never the shared `config.toml`.
`Hyper.Img.Db.Repo.init/2` merges these over its compile-time defaults.

- [Hyper.Cfg.Jails](Hyper.Cfg.Jails.md): VM confinement settings from the `[jails]` table — `config.toml`-only because
the setuid helper enforces the same `uid_gid_range` it reads from this file.

- [Hyper.Cfg.Network](Hyper.Cfg.Network.md): VM egress networking settings from the `[network]` table — `config.toml`-only
because the setuid helper reads the same `uplink` and `clone_pool` to build
each VM's netns, veth, and NAT rules.
- [Hyper.Cfg.Otel](Hyper.Cfg.Otel.md): OpenTelemetry exporter configuration. Resolved from `config :hyper,
Hyper.Cfg.Otel, proto:/endpoint:/headers:` (config.exs), the `[otel]` toml
table, then the standard `OTEL_EXPORTER_OTLP_ENDPOINT` env var.
`config/runtime.exs` calls `exporter_options/1` and feeds the result to
`config :opentelemetry_exporter`.

- [Hyper.Cfg.Tools](Hyper.Cfg.Tools.md): Paths to every external binary Hyper runs, read from the `[tools]` table.
- [Hyper.Cfg.VmLinux](Hyper.Cfg.VmLinux.md): Per-architecture guest-kernel image paths. Operators set `amd64`/`aarch64`
(mapped to `:x86_64`/`:aarch64`) in `config :hyper, Hyper.Cfg.VmLinux, ...` or
the `[vmlinux]` toml table. An unset architecture is simply absent from the map.

- [Hyper.Cluster](Hyper.Cluster.md): Owns this node's participation in the cluster-wide CRDTs: the VM routing
registry (`Hyper.Cluster.Routing`) and the budget telemetry registry
(`Hyper.Cluster.Budget`). One supervisor, one membership story, two
independent DeltaCRDTs.
- [Hyper.Cluster.Budget](Hyper.Cluster.Budget.md): Cluster-wide budget telemetry: one `Hyper.Node.Budget.NodeState` per node,
keyed `{:node, node()}`. A `Horde.Registry` (DeltaCRDT) with `members: :auto`.
- [Hyper.Cluster.Routing](Hyper.Cluster.Routing.md): Cluster-wide VM routing registry: maps `{vm_id, component} -> pid` so any node
can name a VM's processes (`via/1`) and find which machine runs a VM
(`whereis/1`). A `Horde.Registry` (DeltaCRDT) with `members: :auto`, so it
forms over the BEAM cluster libcluster builds.
- [Hyper.Cluster.Scheduler](Hyper.Cluster.Scheduler.md): Picks the node to run a VM on. The first pass reads the gossip-replicated
`Hyper.Node.Budget.NodeState`s (`Hyper.Cluster.Budget.all_states/0`), drops
nodes that cannot fit the spec, and ranks survivors by how many bytes of the
VM's image layers they already have mounted (`colo(N, VM) = sum of |L|` over
shared mounted layers). The result is an ordered candidate list; the chosen
node confirms authoritatively via `Hyper.Node.Budget.admit/2` (see `place/3`).
- [Hyper.Firecracker.Api.ArmRegisterModifier](Hyper.Firecracker.Api.ArmRegisterModifier.md): Provides struct and type for a ArmRegisterModifier

- [Hyper.Firecracker.Api.Balloon](Hyper.Firecracker.Api.Balloon.md): Provides struct and type for a Balloon

- [Hyper.Firecracker.Api.BalloonHintingStatus](Hyper.Firecracker.Api.BalloonHintingStatus.md): Provides struct and type for a BalloonHintingStatus

- [Hyper.Firecracker.Api.BalloonStartCmd](Hyper.Firecracker.Api.BalloonStartCmd.md): Provides struct and type for a BalloonStartCmd

- [Hyper.Firecracker.Api.BalloonStats](Hyper.Firecracker.Api.BalloonStats.md): Provides struct and type for a BalloonStats

- [Hyper.Firecracker.Api.BalloonStatsUpdate](Hyper.Firecracker.Api.BalloonStatsUpdate.md): Provides struct and type for a BalloonStatsUpdate

- [Hyper.Firecracker.Api.BalloonUpdate](Hyper.Firecracker.Api.BalloonUpdate.md): Provides struct and type for a BalloonUpdate

- [Hyper.Firecracker.Api.BootSource](Hyper.Firecracker.Api.BootSource.md): Provides struct and type for a BootSource

- [Hyper.Firecracker.Api.Codec](Hyper.Firecracker.Api.Codec.md): Compile-time JSON codec injected into every generated schema via the
generator's `schema_use` option.
- [Hyper.Firecracker.Api.CpuConfig](Hyper.Firecracker.Api.CpuConfig.md): Provides struct and type for a CpuConfig

- [Hyper.Firecracker.Api.CpuidLeafModifier](Hyper.Firecracker.Api.CpuidLeafModifier.md): Provides struct and type for a CpuidLeafModifier

- [Hyper.Firecracker.Api.CpuidRegisterModifier](Hyper.Firecracker.Api.CpuidRegisterModifier.md): Provides struct and type for a CpuidRegisterModifier

- [Hyper.Firecracker.Api.Drive](Hyper.Firecracker.Api.Drive.md): Provides struct and type for a Drive

- [Hyper.Firecracker.Api.EntropyDevice](Hyper.Firecracker.Api.EntropyDevice.md): Provides struct and type for a EntropyDevice

- [Hyper.Firecracker.Api.Error](Hyper.Firecracker.Api.Error.md): Provides struct and type for a Error

- [Hyper.Firecracker.Api.FirecrackerVersion](Hyper.Firecracker.Api.FirecrackerVersion.md): Provides struct and type for a FirecrackerVersion

- [Hyper.Firecracker.Api.FullVmConfiguration](Hyper.Firecracker.Api.FullVmConfiguration.md): Provides struct and type for a FullVmConfiguration

- [Hyper.Firecracker.Api.InstanceActionInfo](Hyper.Firecracker.Api.InstanceActionInfo.md): Provides struct and type for a InstanceActionInfo

- [Hyper.Firecracker.Api.InstanceInfo](Hyper.Firecracker.Api.InstanceInfo.md): Provides struct and type for a InstanceInfo

- [Hyper.Firecracker.Api.Logger](Hyper.Firecracker.Api.Logger.md): Provides struct and type for a Logger

- [Hyper.Firecracker.Api.MachineConfiguration](Hyper.Firecracker.Api.MachineConfiguration.md): Provides struct and type for a MachineConfiguration

- [Hyper.Firecracker.Api.MemoryBackend](Hyper.Firecracker.Api.MemoryBackend.md): Provides struct and type for a MemoryBackend

- [Hyper.Firecracker.Api.MemoryHotplugConfig](Hyper.Firecracker.Api.MemoryHotplugConfig.md): Provides struct and type for a MemoryHotplugConfig

- [Hyper.Firecracker.Api.MemoryHotplugSizeUpdate](Hyper.Firecracker.Api.MemoryHotplugSizeUpdate.md): Provides struct and type for a MemoryHotplugSizeUpdate

- [Hyper.Firecracker.Api.MemoryHotplugStatus](Hyper.Firecracker.Api.MemoryHotplugStatus.md): Provides struct and type for a MemoryHotplugStatus

- [Hyper.Firecracker.Api.Metrics](Hyper.Firecracker.Api.Metrics.md): Provides struct and type for a Metrics

- [Hyper.Firecracker.Api.MmdsConfig](Hyper.Firecracker.Api.MmdsConfig.md): Provides struct and type for a MmdsConfig

- [Hyper.Firecracker.Api.MsrModifier](Hyper.Firecracker.Api.MsrModifier.md): Provides struct and type for a MsrModifier

- [Hyper.Firecracker.Api.NetworkInterface](Hyper.Firecracker.Api.NetworkInterface.md): Provides struct and type for a NetworkInterface

- [Hyper.Firecracker.Api.NetworkOverride](Hyper.Firecracker.Api.NetworkOverride.md): Provides struct and type for a NetworkOverride

- [Hyper.Firecracker.Api.Operations](Hyper.Firecracker.Api.Operations.md): Provides API endpoints related to operations

- [Hyper.Firecracker.Api.PartialDrive](Hyper.Firecracker.Api.PartialDrive.md): Provides struct and type for a PartialDrive

- [Hyper.Firecracker.Api.PartialNetworkInterface](Hyper.Firecracker.Api.PartialNetworkInterface.md): Provides struct and type for a PartialNetworkInterface

- [Hyper.Firecracker.Api.PartialPmem](Hyper.Firecracker.Api.PartialPmem.md): Provides struct and type for a PartialPmem

- [Hyper.Firecracker.Api.Pmem](Hyper.Firecracker.Api.Pmem.md): Provides struct and type for a Pmem

- [Hyper.Firecracker.Api.RateLimiter](Hyper.Firecracker.Api.RateLimiter.md): Provides struct and type for a RateLimiter

- [Hyper.Firecracker.Api.SerialDevice](Hyper.Firecracker.Api.SerialDevice.md): Provides struct and type for a SerialDevice

- [Hyper.Firecracker.Api.SnapshotCreateParams](Hyper.Firecracker.Api.SnapshotCreateParams.md): Provides struct and type for a SnapshotCreateParams

- [Hyper.Firecracker.Api.SnapshotLoadParams](Hyper.Firecracker.Api.SnapshotLoadParams.md): Provides struct and type for a SnapshotLoadParams

- [Hyper.Firecracker.Api.TokenBucket](Hyper.Firecracker.Api.TokenBucket.md): Provides struct and type for a TokenBucket

- [Hyper.Firecracker.Api.Transport](Hyper.Firecracker.Api.Transport.md): `oapi_generator` client backend for the Firecracker API. Each generated
operation calls `request/1` with a plain map describing the call; this issues
it over the target daemon's HTTP-over-Unix-socket API via `Req` and decodes the
typed response.
- [Hyper.Firecracker.Api.VcpuFeatures](Hyper.Firecracker.Api.VcpuFeatures.md): Provides struct and type for a VcpuFeatures

- [Hyper.Firecracker.Api.Vm](Hyper.Firecracker.Api.Vm.md): Provides struct and type for a Vm

- [Hyper.Firecracker.Api.Vsock](Hyper.Firecracker.Api.Vsock.md): Provides struct and type for a Vsock

- [Hyper.Firecracker.Api.VsockOverride](Hyper.Firecracker.Api.VsockOverride.md): Provides struct and type for a VsockOverride

- [Hyper.Grpc](Hyper.Grpc.md): Public gRPC interface to a Hyper cluster.
- [Hyper.Grpc.Codec](Hyper.Grpc.Codec.md): Translation between the gRPC wire types (`Hyper.Grpc.V0.*`) and Hyper's domain
types. Two entry points, each dispatching by pattern match on the value's type
- [Hyper.Grpc.Endpoint](Hyper.Grpc.Endpoint.md): The gRPC endpoint: logs each call and routes to `Hyper.Grpc.Server`.
- [Hyper.Grpc.Server](Hyper.Grpc.Server.md): gRPC handler for `hyper.grpc.v0.Hyper`. A thin translation layer: each RPC
maps its request to a domain value via `Hyper.Grpc.Codec.from_grpc/1`, calls
the existing `Hyper` BEAM API, and maps the result back with
`Hyper.Grpc.Codec.to_grpc/1` (raising the `GRPC.RPCError` it returns on error).

- [Hyper.Metering.Usage](Hyper.Metering.Usage.md): One VM's metered compute over one wall-clock window: `cpu_usec` is CPU time
the VM *actually executed* between `window_start` and `window_end`, measured
from its cgroup's `cpu.stat` by `Hyper.Node.FireVMM.Meter`.
- [Hyper.SuidHelper.Blockcopy](Hyper.SuidHelper.Blockcopy.md): Chunked ranged copy between block devices, via the setuid helper's
`blockcopy` tool — used to fill a fork delta layer's COW store with exactly
the divergent chunks.

- [Hyper.SuidHelper.Blockdev](Hyper.SuidHelper.Blockdev.md): Block-device queries, via the setuid helper's `blockdev` tool.
- [Hyper.SuidHelper.ChrootJail](Hyper.SuidHelper.ChrootJail.md): Privileged chroot/jail lifecycle, via the setuid helper's `chroot-jail`
subcommands (`prepare` / `remove`). These are built into the helper (no
external binary), so there is no separate `test_system/0` -
`Hyper.SuidHelper.test_system/0` already checks the helper itself is present.

- [Hyper.SuidHelper.Dmsetup](Hyper.SuidHelper.Dmsetup.md): device-mapper operations (snapshot / thin), via the setuid helper's `dmsetup` tool.
- [Hyper.SuidHelper.Losetup](Hyper.SuidHelper.Losetup.md): Loop-device operations, via the setuid helper's `losetup` tool.
- [Hyper.SuidHelper.Network](Hyper.SuidHelper.Network.md): Privileged per-VM egress networking via the setuid helper's `network`
subcommands. The helper derives every address, interface name, and netns path
from `vm_id` + the validated `uid` + the root-owned `[network]` config — the
node passes only those two untrusted values.

- [Hyper.SuidHelper.ThinDump](Hyper.SuidHelper.ThinDump.md): Extract a thin device's provisioned-range map from the pool's metadata, via
the setuid helper's `thin-dump` tool (thin-provisioning-tools). Only valid
while the pool's metadata snapshot is reserved — see
`Hyper.Node.Img.ThinPool.mappings/1`, the sole intended caller.

- [Redist.File](Redist.File.md): Fetches a single raw file from a URL, verifies its SHA-256, and installs it at
a destination path. The raw-file analogue of `Redist.Targz` (used for
assets that ship as plain files rather than tarballs, e.g. vmlinux images).

- [Redist.Sha256](Redist.Sha256.md): Streaming SHA-256 of a file, returned as lowercase hex.
- [Redist.Targz](Redist.Targz.md): Fetches a gzipped tarball from a URL, verifies its SHA-256, and extracts it
into a directory.

- VM
  - [Hyper.Vm](Hyper.Vm.md): A microVM handle (its controller pid) and cluster-wide fork operations.
  - [Hyper.Vm.Id](Hyper.Vm.Id.md): A microVM id and its generator.
  - [Hyper.Vm.Instance](Hyper.Vm.Instance.md): Named instance types - fixed (vCPU, memory) sizes, like cloud instance classes.
  - [Hyper.Vm.Instance.Spec](Hyper.Vm.Instance.Spec.md): Resource bundle for one instance type.
  - [Hyper.Vm.Spec](Hyper.Vm.Spec.md): A request to create a VM: which image to boot, the instance size, the guest
architecture, and optional kernel boot args.

- Node
  - [Hyper.Node](Hyper.Node.md): Per-machine supervisor. Exactly one `Hyper.Node` runs per BEAM node; it owns
every microVM scheduled onto this machine.
  - [Hyper.Node.Budget](Hyper.Node.Budget.md): Public entry point for this node's resource budget. Thin facade over
`Hyper.Node.Budget.Hard`, the per-node accounting GenServer supervised by
`Hyper.Node.Budget.Supervisor`.

  - [Hyper.Node.Budget.Advertiser](Hyper.Node.Budget.Advertiser.md): Owns this node's entry in `Hyper.Cluster.Budget`. Registers a fresh
`Hyper.Node.Budget.NodeState` on start and re-publishes it on demand
(`publish/0`, called on every allocation by `Hyper.Node.Budget.Hard`) and on a
periodic heartbeat (keeps drifting soft-load fresh and restores the
registration if the registry restarted).

  - [Hyper.Node.Budget.Hard](Hyper.Node.Budget.Hard.md): Hard per-node resource accounting. One `Hard` runs per BEAM node (named
`__MODULE__`, started under `Hyper.Node.Budget.Supervisor`) and tracks how much
memory and disk the VMs scheduled onto this machine have reserved.
  - [Hyper.Node.Budget.NodeState](Hyper.Node.Budget.NodeState.md): The per-node resource snapshot published into `Hyper.Cluster.Budget` and read by
`Hyper.Cluster.Scheduler` as the first pass of placement.
  - [Hyper.Node.Budget.Soft](Hyper.Node.Budget.Soft.md): Soft per-node admission check. Where `Hyper.Node.Budget.Hard` tracks memory and
disk reserved from VM specs, `Soft` holds no state: it answers, from this node's
*live* resource monitors (`Sys.Mon`), whether the machine currently has the
instantaneous headroom to take on another VM.
  - [Hyper.Node.Budget.Supervisor](Hyper.Node.Budget.Supervisor.md): Per-node supervisor for the budget subsystem. Runs once per BEAM node and owns
both sides of the budget plus the cluster advertisement
  - [Hyper.Node.FireVMM](Hyper.Node.FireVMM.md): Supervises a single Firecracker microVM, split into four independent children
so no lifecycle invariant rides on the ordering of a flat child list
  - [Hyper.Node.FireVMM.Agent](Hyper.Node.FireVMM.Agent.md): gRPC client to the in-guest agent, dialed through the per-VM relay UDS.
  - [Hyper.Node.FireVMM.Agent.Relay](Hyper.Node.FireVMM.Agent.Relay.md): Per-VM gRPC relay: listens on a host Unix-domain socket and for each
inbound connection performs the Firecracker vsock CONNECT/OK handshake
via `RelayDialer`, then pipes bytes bidirectionally until either side
closes.
  - [Hyper.Node.FireVMM.Agent.RelayDialer](Hyper.Node.FireVMM.Agent.RelayDialer.md): Connects to a Firecracker vsock Unix-domain socket and performs the
host-initiated CONNECT/OK handshake, returning the open socket ready for
use as a transparent byte pipe to the guest agent.
  - [Hyper.Node.FireVMM.BootSpec](Hyper.Node.FireVMM.BootSpec.md): Resolves a `Hyper.Vm.source()` + instance `type` into a concrete, API-shaped
cold-boot spec the `:configuring` state issues: machine config (from the
instance type), a kernel boot source, and a root drive.

  - [Hyper.Node.FireVMM.BootSpec.Cold](Hyper.Node.FireVMM.BootSpec.Cold.md): A resolved cold boot.
  - [Hyper.Node.FireVMM.ChrootJail](Hyper.Node.FireVMM.ChrootJail.md): Places a VM's boot artifacts inside its jailer chroot and points the boot spec
at them.
  - [Hyper.Node.FireVMM.Client](Hyper.Node.FireVMM.Client.md): Per-microVM facade over the generated Firecracker API
(`Hyper.Firecracker.Api.Operations`). One GenServer per VM, registered
cluster-wide via `Hyper.Cluster.Routing.via({vm_id, :client})`. It serializes
every request through `handle_call` (Firecracker's API server is
single-threaded).
  - [Hyper.Node.FireVMM.Client.Opts](Hyper.Node.FireVMM.Client.Opts.md): Start options for `Hyper.Node.FireVMM.Client`. Only `:vm_id` is required;
the socket path is derived from it unless `:socket_path` is given.

  - [Hyper.Node.FireVMM.Core](Hyper.Node.FireVMM.Core.md): The lifecycle-coupled core of one microVM: the jailed firecracker daemon and
its controller, restarted as a pair. Isolated from the API client
(`Hyper.Node.FireVMM.Client`) so the *only* order-sensitive relationship in the
VM tree lives in this two-child supervisor.
  - [Hyper.Node.FireVMM.Daemon](Hyper.Node.FireVMM.Daemon.md): The jailed firecracker OS process for one microVM, as a static child of
`Hyper.Node.FireVMM.Core`.
  - [Hyper.Node.FireVMM.GuestAgent](Hyper.Node.FireVMM.GuestAgent.md): Resolves the path of the `hyper-guest-agent` static musl binary that the
`:guest_agent_build` Mix compiler builds into `priv/guest-agent/` at compile
time. The agent ships inside the app (and its release) -- there is no separate
install step.
  - [Hyper.Node.FireVMM.Jailer](Hyper.Node.FireVMM.Jailer.md): Builds the `hyper-suidhelper jailer` command for one VM.
  - [Hyper.Node.FireVMM.Jailer.Checks](Hyper.Node.FireVMM.Jailer.Checks.md): Host pre-requisite checks for running the jailer. Each check returns
`:ok | {:error, reason}`; `run/0` evaluates them in order and stops at the
first failure.

  - [Hyper.Node.FireVMM.Meter](Hyper.Node.FireVMM.Meter.md): Per-VM compute meter: samples the VM's cgroup `cpu.stat` every second,
accrues the CPU time actually executed, and flushes one
`Hyper.Metering.Usage` window per minute — plus a final one at teardown.
The meter is the FireVMM supervisor's **last** child, so at shutdown it
stops **first**, taking its final reading before the Daemon removes the
cgroup.
  - [Hyper.Node.FireVMM.Meter.Opts](Hyper.Node.FireVMM.Meter.Opts.md): Meter wiring: the VM, its cgroup leaf, and the usage sink.
  - [Hyper.Node.FireVMM.Net](Hyper.Node.FireVMM.Net.md): The per-VM *inner-world* networking contract. Every VM's netns is identical —
`tap0` at 172.30.0.1/30, guest at 172.30.0.2/30 — so a snapshot clone restores
a correct network with zero renumbering; host-side uniqueness is the helper's
job (see `Hyper.SuidHelper.Network`). This module owns the three values that
must agree between the guest kernel cmdline, the Firecracker NIC config, and
the helper: the guest MAC, the `ip=` autoconfig string, and the NIC spec.

  - [Hyper.Node.FireVMM.Opts](Hyper.Node.FireVMM.Opts.md): Per-VM request: instance size + architecture, isolation ids, the kernel
image, optional boot args, and the per-VM `Img.Mutable` layer the VM boots
from. The root device is read from the mutable layer at configure time, so a
VM can only be booted from a mutable layer - never a bare `Hyper.Img`.

  - [Hyper.Node.FireVMM.State](Hyper.Node.FireVMM.State.md): `:gen_statem` controller for one microVM. It drives the boot protocol against a
daemon whose lifecycle is owned by the supervisor (`Hyper.Node.FireVMM.Core`,
`:one_for_all`): the controller does not launch, monitor, or kill the daemon -
if firecracker dies, `Core` restarts the daemon and this controller together,
and `init` simply cold-boots again.
  - [Hyper.Node.FireVMM.State.AwaitingApi](Hyper.Node.FireVMM.State.AwaitingApi.md): Poll the (already-launched) daemon's API socket, then advance to `:configuring`.
  - [Hyper.Node.FireVMM.State.Configuring](Hyper.Node.FireVMM.State.Configuring.md): Stage the kernel + rootfs device into the jail chroot. Enter `:running` after.
  - [Hyper.Node.FireVMM.State.Running](Hyper.Node.FireVMM.State.Running.md): The guest is live. Handles `stop` (-> `:stopping`).
  - [Hyper.Node.FireVMM.State.Stopping](Hyper.Node.FireVMM.State.Stopping.md): Teardown was requested in-band.
  - [Hyper.Node.FireVMM.VmLinux.Manifest](Hyper.Node.FireVMM.VmLinux.Manifest.md): The statically-embedded vmlinux release manifest.
  - [Hyper.Node.FireVMM.VmLinux.Manifest.Build](Hyper.Node.FireVMM.VmLinux.Manifest.Build.md): One kernel build from the manifest.
  - [Hyper.Node.FireVMM.VmLinux.Provider](Hyper.Node.FireVMM.VmLinux.Provider.md): Installs the guest-kernel (vmlinux) images for the current architecture into
`Hyper.Cfg.Dirs.vmlinux_install_dir/0` (`<work_dir>/redist/vmlinux`).
  - [Hyper.Node.Img](Hyper.Node.Img.md): Supervisor for this node's active images, and the entry point for image
operations. Owns
  - [Hyper.Node.Img.Mutable](Hyper.Node.Img.Mutable.md): The per-VM mutable rootfs. On start it activates (or reuses) the image's
read-only `Img.Server`, takes a reference on it, reads the composed device's
size, and asks the node `ThinPool` for a thin volume with that device as a
read-only external origin. `blk_path/1` is the mutable host device the VM
boots from (staged into the jail by `mknod` from this path).
  - [Hyper.Node.Img.Publish](Hyper.Node.Img.Publish.md): Materialize a running VM's disk divergence as a new immutable delta layer.
  - [Hyper.Node.Img.Server](Hyper.Node.Img.Server.md): GenServer representing a single active image on this node.
  - [Hyper.Node.Img.Server.Opts](Hyper.Node.Img.Server.Opts.md): Options for starting an image server.
  - [Hyper.Node.Img.ThinPool](Hyper.Node.Img.ThinPool.md): The node's single dm-thin pool. On start it materialises two sparse backing
files in `scratch_dir` (metadata + data), attaches them as writable loop
devices, zeroes the metadata (so the kernel treats it as a fresh pool), and
creates the `hyper-thinpool` device-mapper pool.
  - [Hyper.Node.Layer](Hyper.Node.Layer.md): Supervisor for this node's mounted layers. Owns a unique `Registry`
(`layer_id -> Layer.Server`) and a `DynamicSupervisor` that holds those
servers, so a layer can be mounted on demand and looked up by its id.

  - [Hyper.Node.Layer.Repo](Hyper.Node.Layer.Repo.md): Repo for looking up layers in the shared layer directory. Currently backed by a flat
file-directory.
  - [Hyper.Node.Layer.Server](Hyper.Node.Layer.Server.md): GenServer responsible for managing a single mounted layer.
  - [Hyper.Node.Reaper](Hyper.Node.Reaper.md): Per-node periodic, liveness-aware garbage collector for per-VM host resources
that an unclean BEAM death can strand: a firecracker cgroup leaf and a
`hyper-rw-<id>` dm volume whose owning processes' `terminate/2` never ran and
whose vm_id never reboots (so `Hyper.Node.Reclaim`, which runs once at boot, and
the relaunch-time cleanup in the FireVMM path, never get a chance to clear it).
  - [Hyper.Node.Reaper.Plan](Hyper.Node.Reaper.Plan.md): Pure reap-decision core for `Hyper.Node.Reaper`. No I/O. Every safety invariant
is a property of these functions: a live vm_id is never a candidate, only an
orphan seen on two consecutive ticks is reaped, and only `hyper-rw-*` dm names
yield candidates (so `hyper-thinpool` / `hyper-img-*` can never be reaped).

  - [Hyper.Node.Reclaim](Hyper.Node.Reclaim.md): Boot-time reclamation of device-mapper and loop devices orphaned by an unclean
shutdown (SIGKILL or `:erlang.halt`, where the owning GenServers' `terminate/2`
never ran to tear them down).
  - [Hyper.Node.Users](Hyper.Node.Users.md): Process running on the `Hyper.Node` responsible for creating and managing POSIX users.
  - [Hyper.Node.Users.State](Hyper.Node.Users.State.md): Bump-pointer + freed-stack id pool. Only ids currently in flight are stored
  - [Hyper.Node.Vmlinux](Hyper.Node.Vmlinux.md): Resolves the guest kernel (vmlinux) image for this node.

- Images
  - [Hyper.Img](Hyper.Img.md): A content-addressed image: an ordered stack of layers, and the entry point for
putting one into the cluster.
  - [Hyper.Img.Db.Blob](Hyper.Img.Db.Blob.md): An immutable, content-addressed leaf object stored on NFS - a base (`P.img`) or
a delta (`L.img`). The `id` is both primary key and identity, so inserts are
conflict-free: two nodes publishing the same bytes write the same row.
  - [Hyper.Img.Db.Gc](Hyper.Img.Db.Gc.md): Cluster-singleton garbage collector that reconciles the `blobs` table against
the shared medium: a `:present` blob whose backing file is gone is a stale row
and is pruned. Runs continuously, one keyset page at a time.
  - [Hyper.Img.Db.Gc.Prune](Hyper.Img.Db.Gc.Prune.md): The delete step of the layer GC, factored out of the `Gc` server so its
safety contracts are testable against a real database without the
cluster-singleton GenServer around them
  - [Hyper.Img.Db.Gc.Sweep](Hyper.Img.Db.Gc.Sweep.md): Pure accounting core for the layer GC.
  - [Hyper.Img.Db.Image](Hyper.Img.Db.Image.md): A derivation - e.g. `P' = P + L`. It is resolved at mount time into an
ordered set of blobs via its `image_layers`. "P'" is a node in the lineage
graph, never a stored file.

  - [Hyper.Img.Db.ImageLayer](Hyper.Img.Db.ImageLayer.md): One rung of an image's assembly chain. `position` 0 is the base blob; ascending
positions are deltas applied on top (each a dm-snapshot COW store over the layer
below). Selecting all rows for an image ordered by `position` yields exactly the
ordered blob list and params needed to emit the dmsetup tables.
  - [Hyper.Img.Db.Lease](Hyper.Img.Db.Lease.md): A single running VM's claim on an image (and transitively, every blob in that
image's chain).
  - [Hyper.Img.Db.Repo](Hyper.Img.Db.Repo.md): Global database of all known layers, and how they relate to each other.
  - [Hyper.Img.OciLoader](Hyper.Img.OciLoader.md): Builds an ext4 rootfs from an OCI image and hands it to `Hyper.Img.create/2`.
  - [Hyper.Img.OciLoader.Umoci](Hyper.Img.OciLoader.Umoci.md): Resolves and (when not operator-provided) installs the `umoci` binary that
`Hyper.Img.OciLoader` uses to flatten OCI image layers.
  - [Hyper.Layer](Hyper.Layer.md): A content-addressed image layer.

- Controls
  - [Controls.Accumulator](Controls.Accumulator.md): Accrues consumption from a monotonically increasing cumulative counter,
tolerating counter resets (the counter's source was destroyed and recreated,
restarting from zero — e.g. a VM's cgroup across a restart).
  - [Controls.Ewma](Controls.Ewma.md): First-order exponential moving average - a discrete low-pass filter (LPF) with
an irregular-sampling-correct gain.
  - [Controls.Rate](Controls.Rate.md): Turns a monotonically increasing byte counter (e.g. `/proc/diskstats` sectors
or `/proc/net/dev` bytes) into a per-second rate.

- Monitoring
  - [Sys.Mon](Sys.Mon.md): Supervises this node's real-time resource monitors and exposes their current
readings to the scheduler via `readings/0`.

  - [Sys.Mon.Cpu](Sys.Mon.Cpu.md): Monitors instantaneous CPU utilization (the soft beta_vcpus signal).
  - [Sys.Mon.DiskBw](Sys.Mon.DiskBw.md): Monitors instantaneous disk bandwidth (the soft beta_disk_bw signal).
  - [Sys.Mon.Mem](Sys.Mon.Mem.md): Monitors instantaneous memory pressure.
  - [Sys.Mon.NetBw](Sys.Mon.NetBw.md): Monitors instantaneous network bandwidth (the soft beta_net_bw signal).
  - [Sys.Mon.Readings](Sys.Mon.Readings.md): A snapshot of every monitored soft metric at one instant. Each field is a
`Sys.Mon.Server.Reading` whose `instant`/`smoothed` carry that metric's domain
type - `cpu` a `Float` fraction, `mem` a `Unit.Information`, `disk_bw`/`net_bw`
a `Unit.Bandwidth`.

  - [Sys.Mon.Sampler](Sys.Mon.Sampler.md): Behaviour for a single soft-metric probe.
  - [Sys.Mon.Server](Sys.Mon.Server.md): Generic monitor process: drives a `Sys.Mon.Sampler` on a fixed period, folds
each reading through a `Controls.Ewma` low-pass filter, and answers `value/1`.
  - [Sys.Mon.Server.Reading](Sys.Mon.Server.Reading.md): A monitor reading: the latest instantaneous and filtered values, each in the
sampler's domain type (a number or any `Unit.Quantity`).

- System
  - [Hyper.SuidHelper](Hyper.SuidHelper.md): Interface to the setuid-root device helper (`hyper-suidhelper`), split by tool
  - [Sys.Arch](Sys.Arch.md): CPU architecture detection for the current machine.
  - [Sys.Linux.Cgroup](Sys.Linux.Cgroup.md): cgroup introspection.
  - [Sys.Linux.Cgroup.V2](Sys.Linux.Cgroup.V2.md): cgroup v2 (unified hierarchy) helpers.
  - [Sys.Linux.Cgroup.V2.Config](Sys.Linux.Cgroup.V2.Config.md): Map which represents the possible configurations of a cgroup
  - [Sys.Linux.Cgroup.V2.CpuStat](Sys.Linux.Cgroup.V2.CpuStat.md): Reads a cgroup v2 `cpu.stat` interface file — the cumulative CPU time the
cgroup's processes have actually executed since the cgroup was created.
  - [Sys.Linux.Fstab](Sys.Linux.Fstab.md): Parsing of `/etc/fstab`-style entries.
  - [Sys.Linux.Fstab.Spec](Sys.Linux.Fstab.Spec.md): A parsed `/etc/fstab` entry.
  - [Sys.Linux.Nss](Sys.Linux.Nss.md): NSS (Name Service Switch) utilities - queries users and groups via `getent`.
  - [Sys.Linux.Nss.Group](Sys.Linux.Nss.Group.md): The group database (`getent group`).
  - [Sys.Linux.Nss.Group.Spec](Sys.Linux.Nss.Group.Spec.md): A parsed `group` entry.
  - [Sys.Linux.Nss.Passwd](Sys.Linux.Nss.Passwd.md): The passwd database (`getent passwd`).
  - [Sys.Linux.Nss.Passwd.Spec](Sys.Linux.Nss.Passwd.Spec.md): A parsed `passwd` entry.
  - [Sys.Linux.Proc.Diskstats](Sys.Linux.Proc.Diskstats.md): Parses `/proc/diskstats` into per-device I/O counters.
  - [Sys.Linux.Proc.Diskstats.Device](Sys.Linux.Proc.Diskstats.Device.md): One `/proc/diskstats` row: a block device and its cumulative read/written bytes.
  - [Sys.Linux.Proc.Meminfo](Sys.Linux.Proc.Meminfo.md): Reads memory totals from `/proc/meminfo`.
  - [Sys.Linux.Proc.Meminfo.Snapshot](Sys.Linux.Proc.Meminfo.Snapshot.md): A point-in-time `/proc/meminfo` reading. Every field maps to a line present
on all Linux kernels (`MemTotal`/`MemFree`/`Buffers`/`Cached` since 2.4,
`MemAvailable` since 3.14).

  - [Sys.Linux.Proc.Mounts](Sys.Linux.Proc.Mounts.md): Reads the currently-mounted filesystems from `/proc/mounts`.
  - [Sys.Linux.Proc.NetDev](Sys.Linux.Proc.NetDev.md): Parses `/proc/net/dev` into per-interface byte counters.
  - [Sys.Linux.Proc.NetDev.Interface](Sys.Linux.Proc.NetDev.Interface.md): One `/proc/net/dev` row: an interface and its cumulative rx/tx bytes.
  - [Sys.Linux.Proc.Stat](Sys.Linux.Proc.Stat.md): Reads kernel counters from `/proc/stat`.
  - [Sys.Linux.Proc.Stat.CpuTimes](Sys.Linux.Proc.Stat.CpuTimes.md): Cumulative jiffies a CPU (the aggregate, or one core) has spent in each state
since boot: `user nice system idle iowait irq softirq steal guest guest_nice`.
  - [Sys.Linux.Proc.Stat.Snapshot](Sys.Linux.Proc.Stat.Snapshot.md): A point-in-time `/proc/stat` reading.
  - [Sys.Linux.Subid](Sys.Linux.Subid.md): Subuid and Subgid utilities
  - [Sys.Linux.Subid.Spec](Sys.Linux.Subid.Spec.md): A subordinate id range - one `/etc/subuid` or `/etc/subgid` entry.
  - [Sys.Posix](Sys.Posix.md): POSIX filesystem helpers.
  - [Sys.Tmp](Sys.Tmp.md): Temporary file/directory helpers.

- Units
  - [Unit.Bandwidth](Unit.Bandwidth.md): A throughput, stored canonically in bytes per second. Build with `bps/1` or the
binary-prefix constructors (`kibps/1`, `mibps/1`, `gibps/1`, `tibps/1`); read back
with `as_bytes_per_sec/1`. Arithmetic (`+`, `-`) and comparison
(`<`, `>`, `<=`, `>=`) come from `Unit.Operators`.

  - [Unit.Information](Unit.Information.md): A quantity of data, stored canonically in bytes. Build with `bytes/1` or the
binary-prefix constructors (`kib/1`, `mib/1`, `gib/1`, `tib/1`); read back with
the matching `as_*` accessor. Arithmetic (`+`, `-`) and comparison
(`<`, `>`, `<=`, `>=`) come from `Unit.Operators`.

  - [Unit.Operators](Unit.Operators.md): Operator overloading for `Unit.Quantity` types.
  - [Unit.Quantity](Unit.Quantity.md): A one-dimensional physical quantity backed by a single canonical integer
(bytes, nanoseconds, bytes/sec, ...). Implementing this is all a unit type
needs to get `+`, `-`, and the ordering operators from `Unit.Operators`.
  - [Unit.Time](Unit.Time.md): A duration, stored canonically in nanoseconds. Build with `ns/1`/`us/1`/`ms/1`/`s/1`,
read back with the matching `as_*` accessor. A `Time` is a distinct struct, so it
cannot be mixed with other dimensions (`Information`, `Bandwidth`). Arithmetic
(`+`, `-`) and comparison (`<`, `>`, `<=`, `>=`) come from `Unit.Operators`.

- Exceptions
  - [Hyper.Cfg.MissingError](Hyper.Cfg.MissingError.md): Raised when a required config value is absent from every permitted source.

## Mix Tasks

- [mix firecracker.install](Mix.Tasks.Firecracker.Install.md): Downloads, verifies, and installs the pinned Firecracker release (v1.16.0)
for the current CPU architecture.
- [mix suidhelper.install](Mix.Tasks.Suidhelper.Install.md): Builds, stamps, and installs the Rust setuid helper.