keyboot
keyboot is a greenfield boot stage that runs after GRUB and before your OS’s
init. In one boot it decrypts a LUKS keyfile inside its own initramfs, uses that
key to open every LUKS device backing the root zpool, imports the pool, lets you
pick a boot environment (TTY or SSH), and kexecs into that BE’s own kernel.
The same artifact is also a netbootable rescue shell, an unattended installer,
and a memtest launcher (selected by keyboot.mode=). It targets Debian, Gentoo,
and Alpine on UEFI and BIOS.
GRUB ─▶ keyboot (unlock env) ─▶ kexec ─▶ your OS (ZFS-on-LUKS root)
Where to start
| You want to… | Read |
|---|---|
| Install keyboot + an OS on a blank box | Bare-metal install |
| Bootstrap the installer in a live env | Installer bootstrap |
| Run day-2 ops (update, snapshots, keys, BEs) | Operator guide |
| Fix a broken host | Disaster recovery |
| Understand how it fits together | Architecture |
| Understand the unlock path | Unlock flow |
| Unlock from a browser (passphrase, mTLS, security key) | Browser unlock |
| Drive real-hardware tests | Hardware-test runbook |
Install in one line (from a live env)
curl -fsSL https://packages.osterman.co/keyboot/install-os | sh # musl live env (Alpine)
(For a glibc rescue, see installer-bootstrap / Hetzner deploy.)
The rest of the docs
Use the sidebar. Reference: architecture, unlock-flow, browser unlock, dataset layout, supported OSes, memtest, RAM rescue, native package repos, USB rescue, Hetzner deploy. Decisions: the ADRs record the locked design choices and the why.
SPEC.md (in the repo) is the authoritative design of record; this site is the
day-2, operator-facing view.