# linuxboot/heads architecture

> Architecture diagram of the GitHub repository linuxboot/heads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linuxboot/heads
- Repository: https://github.com/linuxboot/heads

## Overview

Heads is a firmware and boot-security project for commodity laptops and servers. Its intended user outcome is a boot path rooted in free firmware, with firmware and filesystem integrity measured or verified before handing off to an operating system. The repository also includes image-cleaning utilities for Intel Management Engine firmware. The README documents the major boot, trust, TPM, key, and board-configuration capabilities; most runtime implementation files were not sampled, so runtime links are kept sparse rather than inferred from filenames.

Main entry points: [`initrd`](https://github.com/linuxboot/heads/tree/master/initrd) (Boot environment), [`modules/coreboot`](https://github.com/linuxboot/heads/blob/master/modules/coreboot) (Coreboot firmware), [`modules/linux`](https://github.com/linuxboot/heads/blob/master/modules/linux) (Linux payload), [`initrd/bin`](https://github.com/linuxboot/heads/tree/master/initrd/bin) (Boot measurement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot runtime"]
  node_coreboot["Coreboot firmware"]
  node_linux["Linux payload"]
  node_initrd["Boot environment"]
  node_bootflow["Boot selection"]
  node_gui["Boot interface"]
end

subgraph group_trust["Integrity and secrets"]
  node_filesystem["Filesystem checks"]
  node_measure["Boot measurement"]
  node_tpm["TPM operations"]
  node_keymgmt["Key handling"]
  node_gpg["GPG verification"]
  node_hotp["HOTP and TOTP"]
end

subgraph group_platform["Platform support"]
  node_boards["Board definitions"]
  node_config["Firmware configs"]
  node_blobs["Firmware blobs"]
  node_winterfell["Winterfell init<br/>[uinit.go]"]
end

subgraph group_firmwaretools["Firmware utilities"]
  node_cleaner["ME cleaner<br/>[me_cleaner.py]"]
  node_meparser["ME update parser"]
end

node_user(("Device operator"))

node_user -.->|"boots device"| node_coreboot
node_coreboot -.->|"loads payload"| node_linux
node_linux -.->|"uses initrd"| node_initrd
node_initrd -.->|"selects boot"| node_bootflow
node_initrd -.->|"offers interface"| node_gui
node_initrd -.->|"verifies filesystems"| node_filesystem
node_initrd -.->|"measures state"| node_measure
node_measure -.->|"uses TPM"| node_tpm
node_initrd -.->|"handles keys"| node_keymgmt
node_initrd -.->|"checks signatures"| node_gpg
node_initrd -.->|"supports attestation"| node_hotp
node_boards -.->|"defines variants"| node_config

click node_coreboot "https://github.com/linuxboot/heads/blob/master/modules/coreboot"
click node_linux "https://github.com/linuxboot/heads/blob/master/modules/linux"
click node_initrd "https://github.com/linuxboot/heads/tree/master/initrd"
click node_bootflow "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_gui "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_filesystem "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_measure "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_tpm "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_keymgmt "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_gpg "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_hotp "https://github.com/linuxboot/heads/tree/master/initrd/bin"
click node_boards "https://github.com/linuxboot/heads/tree/master/boards"
click node_config "https://github.com/linuxboot/heads/tree/master/config"
click node_blobs "https://github.com/linuxboot/heads/tree/master/blobs"
click node_cleaner "https://github.com/linuxboot/heads/blob/master/blobs/utils/me_cleaner/me_cleaner.py"
click node_meparser "https://github.com/linuxboot/heads/blob/master/blobs/xx20/me7_update_parser.py"
click node_winterfell "https://github.com/linuxboot/heads/blob/master/unmaintained_boards/UNTESTED_winterfell/uinit.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_coreboot,node_linux,node_initrd,node_bootflow,node_gui toneBlue
class node_filesystem,node_measure,node_tpm,node_keymgmt,node_gpg,node_hotp toneAmber
class node_boards,node_config,node_blobs,node_winterfell toneMint
class node_cleaner,node_meparser toneRose
class node_user toneIndigo
```

## Components

### Boot runtime

- [Coreboot firmware](https://github.com/linuxboot/heads/blob/master/modules/coreboot): `modules/coreboot`
- [Linux payload](https://github.com/linuxboot/heads/blob/master/modules/linux): `modules/linux`
- [Boot environment](https://github.com/linuxboot/heads/tree/master/initrd): `initrd`
- [Boot selection](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [Boot interface](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`

### Integrity and secrets

- [Filesystem checks](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [Boot measurement](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [TPM operations](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [Key handling](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [GPG verification](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`
- [HOTP and TOTP](https://github.com/linuxboot/heads/tree/master/initrd/bin): `initrd/bin`

### Platform support

- [Board definitions](https://github.com/linuxboot/heads/tree/master/boards): `boards`
- [Firmware configs](https://github.com/linuxboot/heads/tree/master/config): `config`
- [Firmware blobs](https://github.com/linuxboot/heads/tree/master/blobs): `blobs`
- [Winterfell init](https://github.com/linuxboot/heads/blob/master/unmaintained_boards/UNTESTED_winterfell/uinit.go): `unmaintained_boards/UNTESTED_winterfell/uinit.go`

### Firmware utilities

- [ME cleaner](https://github.com/linuxboot/heads/blob/master/blobs/utils/me_cleaner/me_cleaner.py): `blobs/utils/me_cleaner/me_cleaner.py`
- [ME update parser](https://github.com/linuxboot/heads/blob/master/blobs/xx20/me7_update_parser.py): `blobs/xx20/me7_update_parser.py`

### Other components

- **Device operator**

## Connections

- Device operator → Coreboot firmware: boots device
- Coreboot firmware → Linux payload: loads payload
- Linux payload → Boot environment: uses initrd
- Boot environment → Boot selection: selects boot
- Boot environment → Boot interface: offers interface
- Boot environment → Filesystem checks: verifies filesystems
- Boot environment → Boot measurement: measures state
- Boot measurement → TPM operations: uses TPM
- Boot environment → Key handling: handles keys
- Boot environment → GPG verification: checks signatures
- Boot environment → HOTP and TOTP: supports attestation
- Board definitions → Firmware configs: defines variants