╔═══════════════╗
    ║   ▄███████▄   ║
    ║  ███████████  ║
    ║  ███┌───┐███  ║
    ║  ███│ ◆ │███  ║
    ║  ███│   │███  ║
    ║  ███└─▲─┘███  ║
    ║  ▀█████████▀  ║
    ║    ▀█████▀    ║
    ╚═══════════════╝

aegis-boot

Signed boot. Any ISO. Your keys.

A signed UEFI Secure Boot rescue environment that lets operators pick any ISO from a USB stick's data partition and kexec into it — without leaving the chain of trust.

Status: pre-1.0. CHANGELOG.md has the per-release detail; v1.0.0 is gated on the multi-vendor real-hardware sweep (#51).

See it in action

Three CLI demos that load instantly — no setup, no flash, no risk to any disk:

aegis-boot tour — what aegis-boot is in 30 seconds, with the 4-command path to a working stick:

aegis-boot recommend — browse the curated catalog of 20 known-good ISOs, each marked with its Secure Boot signing chain:

aegis-boot recommend ubuntu-24.04-live-server — drill into a single entry to see the verified-download recipe:

Deeper-dive demos of the destructive flash flows + the rescue-tui under QEMU + OVMF SecureBoot are tracked in #348 — those need real hardware (or a loop device) to record.

What it does

1. Flash an aegis-boot image to a USB stick (aegis-boot flash or dd).
2. Drop .iso files onto the AEGIS_ISOS partition.
3. Boot the stick on any UEFI machine with Secure Boot enabled.
4. A minimal ratatui TUI lists the ISOs; the operator selects one.
5. kexec_file_load(2) hands off to the selected ISO's kernel.

Boot chain: UEFI firmware → shim (MS-signed) → grub (Canonical-signed) → rescue kernel → our initramfs → rescue-tui → kexec_file_load → selected ISO's kernel. Full rationale: ADR 0001.

How it differs from Ventoy / Rufus / balenaEtcher

aegis-boot is the right pick when you need to boot operator-supplied ISOs without disabling Secure Boot or trusting a global third-party MOK. Unsigned ISO kernels are refused with a clear error and a mokutil --import command for the specific signing key — see docs/UNSIGNED_KERNEL.md.

Quickstart — operators

Install the operator CLI:

Pre-built binaries ship today for Linux x86_64 and macOS arm64 (Apple Silicon). On Windows, the recommended path is Rufus + our signed .img — no need to install the aegis-boot CLI. Intel-Mac / Windows operators who want the CLI anyway can build from source (cargo install --path crates/aegis-cli).

# Cosign-verified install from the latest GitHub release.
curl -sSL https://raw.githubusercontent.com/aegis-boot/aegis-boot/main/scripts/install.sh | sh

# OR via Homebrew (macOS Apple Silicon only):
brew tap aegis-boot/aegis-boot https://github.com/aegis-boot/aegis-boot
brew install aegis-boot

# OR on NixOS / with Nix installed:
nix run github:aegis-boot/aegis-boot -- flash /dev/sdX --yes
# Or persist: nix profile install github:aegis-boot/aegis-boot

# Or pin a version: sh install.sh --version v0.15.0
# Or skip cosign (NOT recommended): sh install.sh --no-verify
# Build from source: see BUILDING.md.

Each release ships a static-musl aegis-boot-x86_64-linux binary plus its Sigstore cosign signature + certificate; the installer checks the cert is bound to this repo's release.yml workflow before installing. See docs/RELEASE_NOTES_FOOTER.md for the manual cosign verify-blob recipe.

Then the operator flow — pick one:

Fastest path — aegis-boot quickstart

# Empty stick → booted rescue with Alpine 3.20 in under 10 min (#352)
sudo aegis-boot quickstart /dev/sdc

Thin wrapper over init --profile minimal --yes --direct-install. Single signed-chain stick + Alpine 3.20 Standard (~200 MiB) ready in the rescue-tui menu. Device argument is required — no auto-detect, by deliberate design (data-loss risk on a misclassified mount). See aegis-boot quickstart.

Three-distro kit — aegis-boot init

# Empty stick → rescue-ready with 3 ISOs (~5 GiB)
sudo aegis-boot init /dev/sdc --yes

Composes doctor → flash → fetch + add for every ISO in the default panic-room profile (Alpine 3.20 + Ubuntu 24.04 Server + Rocky 9). Produces one attestation manifest spanning the whole run. See aegis-boot init for profiles and options.

Step-by-step — when you want a custom ISO set

# 0. (recommended) check host + stick health before doing anything destructive
aegis-boot doctor

# 1. browse the curated catalog — known-good signed-or-MOK-needed ISOs
aegis-boot recommend
aegis-boot recommend ubuntu-24.04-live-server   # one entry's download recipe

# 2. write aegis-boot to a USB stick (3-step guided; auto-detects removable drives)
sudo aegis-boot flash             # or: sudo aegis-boot flash /dev/sdc

# 3. add ISOs to the stick (auto-detects mount; copies sidecars too)
aegis-boot add ~/Downloads/ubuntu-24.04.2-live-server-amd64.iso
aegis-boot list                   # show what's on the stick

# 4. plug the stick into a target machine, boot from it (UEFI + SB enabled)
#    The TUI discovers ISOs, shows verification status, and kexecs on Enter.

Operator end-to-end walkthrough: docs/INSTALL.md. Common errors and their fixes: docs/TROUBLESHOOTING.md.

Quickstart — developers

cargo build --release
./scripts/build-initramfs.sh
./scripts/mkusb.sh                # produces out/aegis-boot.img

# Boot the simulated stick under QEMU + OVMF SecBoot
mkdir -p test-isos && cp ~/Downloads/*.iso test-isos/
./scripts/qemu-loaded-stick.sh -d ./test-isos -a usb -i

Full developer loop: docs/LOCAL_TESTING.md.

Components

Documentation

For operators

• docs/INSTALL.md — flash → add ISOs → boot → select, end-to-end
• docs/CLI.md — aegis-boot CLI reference
• docs/TROUBLESHOOTING.md — common errors and fixes (errno 61, won't-boot, etc.)
• docs/UNSIGNED_KERNEL.md — what to do when an ISO's kernel isn't signed
• docs/USB_LAYOUT.md — what's on the stick (ESP + AEGIS_ISOS)

For contributors

• CONTRIBUTING.md — patch workflow, conventions, PR bar
• AGENTS.md — vendor-neutral guidance for AI coding agents (security guardrails, sensitive surfaces, common traps)
• docs/ARCHITECTURE.md — one-page mental model
• BUILDING.md — reproducible build setup (Docker + Nix)
• docs/LOCAL_TESTING.md — 8-stage local CI equivalent
• docs/rescue-tui-serial-format.md — serial-output contract + the aegis.test=<NAME> harness modes that aegis-hwsim drives
• docs/attestation-manifest.md — on-ESP attestation-manifest wire format
• docs/adr/ — Architecture Decision Records
• docs/compatibility/iso-matrix.md — per-distro kexec compatibility

Security

• SECURITY.md — vulnerability reporting (use private advisory; 7-day ack SLA)
• THREAT_MODEL.md — UEFI Secure Boot threat model (PK/KEK/MOK/SBAT)

Project

• CHANGELOG.md | ROADMAP.md | CODE_OF_CONDUCT.md

Runtime configuration

rescue-tui reads these environment variables (set on the kernel cmdline or in the /init script):

scripts/mkusb.sh reads: OUT_DIR, IMG, DISK_SIZE_MB (default 2048), ESP_SIZE_MB (400), DATA_LABEL (AEGIS_ISOS), DATA_FS (exfat default, also fat32 or ext4; #243), SHIM_SRC, GRUB_SRC, KERNEL_SRC, INITRD_SRC.

Build environment

• Rust 1.95.0 (build-toolchain pin in Dockerfile.locked + rust-toolchain.toml; MSRV is 1.88, declared via rust-version in workspace Cargo.toml)
• Ubuntu 22.04 base (Docker) or a Nix flake
• No EDK II / UEFI toolchain — we use shim + signed distro kernels instead

License

Dual-licensed under either of:

• Apache License 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option. Contributions are accepted under the same dual license; see CONTRIBUTING.md.

See NOTICE for upstream attribution of the signed Secure Boot components (shim, grub, kernel) distributed as part of aegis-boot media.