# Heads Linux Boot: coreboot payload setup and testing

> Heads is a minimal Linux boot payload for coreboot or LinuxBoot systems, aimed at developers who want measured boot, attestation, and filesystem verification. Docker supports software builds and QEMU tests before risky SPI flashing.

**linuxboot/heads** — A minimal Linux that runs as a coreboot or LinuxBoot(UEFI's DXE replacement) ROM payload to provide a secure, flexible boot environment for laptops, workstations and servers.

- Repository: https://github.com/linuxboot/heads
- Website: https://osresearch.net/
- Stars: 1,602 · Forks: 212
- Language: Makefile
- License: GPL-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/linuxboot-heads

## Heads targets the firmware layer below Linux

Heads is a minimal Linux configuration intended to run as a coreboot payload or as a LinuxBoot replacement for UEFI DXE. Its stated audience is technically experienced owners of laptops, workstations, and servers who want greater control over the early boot environment. It is not an ordinary Linux distribution or a general-purpose installation assistant.

The project addresses several problems in the firmware path. Its goals include using free software during boot, moving the root of trust into hardware or at least the ROM bootblock, measuring firmware state, attesting that state, and measuring filesystems. The repository topics also connect Heads with TPMs, measured boot, verified boot, SRTM, ownership, and bootroms.

This focus changes the consequences of deployment. Firmware runs before the operating system, so an error can affect startup, recovery, or the machine itself. The README says Heads is a work in progress and is not yet ready for non-technical users. It warns that installation can require disassembly, an external SPI flash programmer, and carries a risk of destruction. Those warnings are central to the project's adoption decision, not incidental caveats.

## The Heads boot sequence and trust checks

The documented boot sequence is /init, gui-init, kexec-select-boot, and operating-system handoff. This sequence places a Linux userspace between the platform firmware and the selected operating system. The repository documentation also covers GUI elements built with whiptail wrappers, integrity reports, and error flows.

Heads records and checks state rather than treating firmware as an invisible preliminary stage. The security documentation identifies measured boot, TPM attestation using TOTP or HOTP, GPG boot signing, LUKS with a Disk Unlock Key, and fail-closed behavior. The TPM documentation assigns PCR values, defines sealing policies, and describes the SRTM chain. Those mechanisms can detect changes and stop a boot when expected conditions are absent.

The implementation has dependencies that must be understood before flashing. TPM behavior varies by board, sealed policies depend on specific measurements, and recovery requires careful handling of the TPM owner, GPG credentials, Disk Recovery Key, and LUKS DUK. A hardware root of trust does not remove the need to configure the policy correctly. Nor does a successful measurement prove that the hardware and deployment support the intended result. Heads gives the boot path a security model, but board support and secret custody remain separate engineering tasks.

## Building Heads with the Docker wrapper

The README identifies Docker CE and ./docker_repro.sh as the supported and tested workflow. The wrapper supplies the build stack and a runtime containing QEMU, swtpm, and canokey-qemu. This avoids requiring host-side QEMU or swtpm installations for the documented development path.

First clone the repository with its complete history. The README says tags must be available because the build uses git describe --tags when naming artifacts. The following commands retrieve the project and enter its directory.

```bash
git clone https://github.com/linuxboot/heads.git
cd heads
```

A shallow clone can lack the tag or abbreviated Git suffix used by the build. The README gives the following repair commands when a clone was made with --depth 1 or when artifact names end in `_-`.

```bash
git fetch --unshallow origin
git fetch --tags origin
```

The full history and tags should be available before building if reproducible artifact naming matters. The Makefile also distinguishes a clean, tagged release from a development build. Development names include a timestamp and `git describe` information, which helps identify the source state represented by an artifact.

## A QEMU board build provides a first software test

The README gives a direct quick-start command for a board and another command that runs the QEMU target. The exact board name must be one of the directory names under `boards/`. The first command builds an EOL x230 target. The second builds and runs a QEMU target with TPM2 support.

```bash
./docker_repro.sh make BOARD=EOL_x230-hotp-maximized
```

The next command starts the documented QEMU board workflow in software. According to the README, Docker includes the required runtime components, so this is the first meaningful check before considering a physical board.

```bash
./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2 run
```

For CI, agents, or other non-interactive contexts, the README says the wrapper still needs a pseudo-terminal. It gives a `script` command that allocates one, propagates the exit status, and flushes output. `HEADS_DISABLE_USB=1` skips USB-token passthrough and its three-second abort window.

```bash
script -qefc "HEADS_DISABLE_USB=1 ./docker_repro.sh make BOARD=EOL_t480-hotp-maximized"
```

The command records a session in `./typescript` by default. The README says that file is ignored by Git. A developer who does not want the transcript can pass `/dev/null` as the trailing argument to `script`, but that option is not needed for the initial build. The QEMU path can expose build and boot problems, yet it cannot verify every electrical, SPI, TPM, or write-protection property of a real computer.

## Board compatibility and physical flashing remain separate checks

Heads outputs are organized by architecture and board under `build/<arch>/<board>/`. The documentation states that x86 boards use `build/x86/`, while `UNTESTED_talos-2` uses `build/ppc64/` and has a Talos-specific `.tgz` layout. The filename rules and size or hash manifest semantics are documented separately because an output file is not enough to establish what it contains.

Board selection should begin with doc/BOARDS_AND_TESTERS.md. The README does not claim that every directory under `boards/` is equally ready for deployment. It also points to wp-notes.md for board-specific flash write-protection status. The hardware compatibility page named in the README is not a working link, so the repository instead points maintainers to board configurations, HCL anchors, and the compatibility list in doc/modules.md.

The deployment sequence should therefore remain conservative. Build the selected target, inspect the artifact directory, read the board notes, and consult the relevant tester or maintainer information before opening the device. The README's prerequisite documentation covers USB security dongles, operating system requirements, and flashing methods. It does not provide one universal flashing command for every supported machine. That absence is a safety boundary. A generic command based on another board could ignore write protection, image layout, or hardware differences.

Physical installation remains more consequential than a QEMU run. The project specifically warns about disassembly, external programming equipment, possible destruction, and frustration. A successful QEMU boot should be treated as a prerequisite for further checks, not as proof that a real board is ready to flash.

## Maintenance, upgrades, and GPL-2.0 implications

The repository is not archived. Its last push was on 2026-10-11. The available release history includes v0.2.1 from 2017-04-24, v0.2.0 from 2017-04-13, and v0.1.0 from 2017-02-01. The repository can therefore be changed, but the available release history does not show a recent sequence of numbered releases. An adopter should distinguish current repository activity from release cadence.

Upgrades also have a firmware-specific cost. A new commit can alter board files, build layers, modules, security policies, TPM handling, or artifact names. The documentation separates build artifacts, module selection, reproducible builds, TPM assignments, and stale-build debugging into different reference documents. That separation indicates that a source update is not equivalent to merely replacing one binary on disk. The selected board configuration and any generated state need to be checked against the current documentation.

Heads is distributed under GPL-2.0, as identified by the repository's license and `COPYING` file. That identifier describes the project's licensing terms, but this article does not provide legal advice. Anyone redistributing modified or combined firmware should review the applicable GPL-2.0 obligations and preserve the required notices and source availability where applicable.

Maintenance costs include rebuilds, board validation, key and secret handling, TPM policy review, and hardware testing. The documentation's mention of reproducible builds and hash manifests helps compare artifacts, but it does not eliminate the need to identify the correct board and revision before deployment.

## Where Heads is the wrong tool

Heads is the wrong choice for a non-technical user seeking a conventional Linux installation. The README explicitly says the project is not yet ready for that audience. It is also unsuitable for a machine whose board configuration, write-protection status, or flashing procedure has not been documented. A generic Linux build result cannot substitute for board-specific hardware knowledge.

The project is not a drop-in UEFI distribution installer in the ordinary sense. Its coreboot or LinuxBoot placement, TPM measurements, attestation choices, LUKS DUK, and operating-system handoff create additional configuration decisions. Organizations that require a centrally managed standard OS image but do not have firmware expertise should compare it with a conventional Linux installation before selecting it.

QEMU is useful for a first check, but it does not reproduce all real-board behavior. TPM implementations, SPI flash hardware, firmware write protection, and device-specific boot paths can differ. The README's own warning about physical installation confirms that the software build is not the full deployment procedure. Heads addresses early boot security for technically capable users; it does not remove hardware risk or eliminate board-specific verification.

## Conclusion

Heads fits developers who already work with coreboot, SPI flash hardware, TPM-backed attestation, and reproducible firmware builds. It is a poor choice for ordinary users or anyone unwilling to validate board-specific procedures. Before adoption, check doc/BOARDS_AND_TESTERS.md, inspect the relevant write-protection notes, and confirm artifacts under build/<arch>/<board>/ before touching hardware.

## FAQ

### Can Heads be tested without physical hardware?

Yes. The README says the Docker workflow includes QEMU, swtpm, and canokey-qemu, allowing software builds and tests before flashing a real board.

### Is Heads ready for non-technical users?

No. The README says it is a work in progress and warns that installation can require disassembly, an external SPI flash programmer, and a risk of destruction.

### Where does Heads store build artifacts?

Artifacts are stored under `build/<arch>/<board>/`. Most x86 boards use `build/x86/`, while `UNTESTED_talos-2` uses `build/ppc64/` and a Talos-specific archive layout.

### Does Heads require Docker for its documented build workflow?

The README says the supported and tested workflow uses the provided Docker wrappers and a versioned Docker image. It states that this avoids requiring host-side QEMU or swtpm installations.

## Sources

- [License: GPL-2.0](https://github.com/linuxboot/heads/blob/master/LICENSE)
- [linuxboot/heads on GitHub](https://github.com/linuxboot/heads)
- [Project website](https://osresearch.net/)
- [README](https://github.com/linuxboot/heads/blob/master/README.md)
- [Releases](https://github.com/linuxboot/heads/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linuxboot-heads