Table of contents
  1. Prerequisites for Heads
    1. Required equipment
    2. Supported devices
    3. USB Security Dongles (aka security token aka smartcard)
      1. USB Security dongle compatibility:
      2. Supported USB Security dongles:
    4. EC firmware & customizations 🔧
  2. Emulated devices

Prerequisites for Heads

Required equipment

To install Heads on a physical device, you will need:

  • Supported motherboard or laptop (see below)
  • A heads compatible USB security dongle (see below)
  • A heads compatible storage device for your public GPG key (USB flash drive)

If your device requires external flashing (see below), make sure you check the package type (SOIC8 vs WSON8) and the flash chip model first so you can pick a compatible programmer and clip/probe (1.8V vs 3.3V devices need different support).

Supported devices

Please see the current heads source for up-to-date supported board configurations.

Note repeatedly untested boards from willing to test board owners were moved to unmaintained_boards directory and aren’t built by CircleCI anymore

If you have an external programmer and are techsavvy enough to bring their support back yourself, read the Community page and reach out. I will gladly assist in your quest :)

USB Security Dongles (aka security token aka smartcard)

All USB Security dongles used with Heads must support OpenPGP for storing your private key and signing /boot contents.

HOTP verification is optional but provides automatic firmware verification at boot. Without HOTP, you’ll use TPMTOTP (manual verification with your phone). Most board configurations are available in both HOTP and non-HOTP variants, though some vendors only support HOTP-enabled configurations.

USB Security dongle compatibility:

Compatible dongles must support the specialized HOTP verification protocol developed by Nitrokey. For technical details about this protocol, see the Nitrokey HOTP verification project.

NOTE - Heads does NOT support FIDO2 or U2F authentication. Be careful when purchasing to buy a compatible key.

NOTE - HOTP remote attestation is supported from Librem/NovaCustom/Nitropad platforms by default, Otherwise HOTP is explicitely supported by board configurations having hotp in their board names.

NOTE - The NitroKey 3 comes in three sizes: USB A, A-mini and C. Nk3a mini (USB A-mini) is the one most shipped with novacustom and nitropads.

  • ThinkPads have USB A ports, not C. After that, it’s users preferences for the form factor desired.

Supported USB Security dongles:

Manufacturer Model OpenPGP HOTP verification Compatible
Yubico YubiKey 5 Series ✅ ❌ OpenPGP only
Nitrokey Nitrokey Pro 2 âś… âś… Full support
Nitrokey Nitrokey Storage 2 âś… âś… Full support
Nitrokey Nitrokey 3 âś… âś… Full support
Purism Librem Key âś… âś… Full support

Notes:

  • OpenPGP only: Can be used with non-HOTP board configurations (manual TPMTOTP verification).
  • Full support: Can be used with both HOTP and non-HOTP board configurations.

NOTE - If you prefer not to use USB security dongles or want simplified security procedures, see the Purism Boot Modes documentation for information about Basic and Restricted boot modes that provide different security/usability trade-offs.

EC firmware & customizations 🔧

The Embedded Controller (EC) is responsible for platform functions such as keyboard hotkeys, keyboard layout enforcement, battery/charging policies, and thermal control. On many supported ThinkPad boards the EC can only be updated as part of the vendor BIOS update process. Because of that, apply any EC changes you require via vendor firmware before performing the initial Heads flash.

Common EC customizations and caveats:

  • Keyboard mappings / key swaps (e.g., allowing an X220 keyboard layout on an X230).
  • Battery whitelisting or vendor-specific battery policies that can prevent booting with third-party batteries.
  • Power, charging, or thermal behavior changes that alter how the system charges or manages thermals.

Recommended workflow:

  1. If you do not need EC changes: update the vendor BIOS/firmware first, then proceed with SPI backups and Heads flashing.
  2. If you do need EC changes: apply and verify them using vendor tools/firmware before flashing Heads; ensure the system boots normally under vendor firmware.

Important pre-update step — apply vendor BIOS/EC updates first:

  • Prepare a USB bootable disk following El Torito instructions (for example: https://askubuntu.com/questions/651281/write-bootable-bios-update-iso-to-usb-stick), boot the prepared USB disk, and run the vendor’s BIOS/firmware upgrade utility to apply EC updates. Doing this ensures vendor EC changes (keyboard mappings, battery whitelists, power/thermal policies) are applied prior to installing Heads and reduces the risk of unexpected behavior.
  • Be sure the device is on AC power and the battery is charged before starting firmware updates; record the vendor firmware version and keep a copy of the firmware image and your SPI backups in a safe place.
  1. Always back up BIOS/EC images and SPI dumps before making firmware changes.

References:

Note: Heads/Coreboot will not modify an EC. If a board requires a custom EC blob, follow the board-specific build instructions and include the blob at build time.

Note: All current Heads boards use a modern architecture where the Intel Management Engine (ME) is deactivated and the Intel Flash Descriptor (IFD) is unlocked. On older Intel platforms (up to Ivy Bridge/3rd gen), the ME can be neutered (most modules removed), while on newer platforms (Skylake and later), the ME is deactivated using HAP bits or other methods. The historical distinction between “Legacy” and “Maximized” boards is no longer relevant as of 2024, since all supported boards now use the approach that was previously called “maximized.”

Emulated devices

For further information, see Emulating Heads