Face-unlock for Linux — login, sudo, lock screen — that works in the dark, resists photo & screen spoofs, and never stores your face as an image.
Works with the camera you have: an IR (Windows Hello) camera unlocks the full secure tier, a regular webcam gives convenient screen unlock, and a fingerprint reader slots in as a companion factor.
Engineered to meet or beat Windows Hello, on a fully-open, commercially-clean stack.
| 🌑 Works in the dark | Active infrared recognition (Windows-Hello cameras) — no ambient light needed. |
| 🔒 Unlocks everything | Login greeter, lock screen, sudo, polkit — with the password always as fallback (no lockout, ever). |
| 🗝️ Opens your keyring | On IR hardware a face match TPM-unseals your login password so the wallet unlocks at login — like Hello. |
| 👁️ Real liveness | Algorithmic IR anti-spoof gate + opt-in passive blink detection (no prompt, no action). |
| 🧬 Privacy by design | Stores 512-D embeddings, never images; AES-256-GCM encrypted, key TPM-sealed to your boot state. |
| 🎚️ Adapts to your hardware | IR camera → Secure tier · RGB-only → Convenience (screen-unlock) tier · fingerprint reader → companion factor. All auto-detected. |
| 🩺 Self-healing | A live TUI (irlume tui) detects & one-key-fixes daemon/PAM/reader/config faults. |
| 📦 Self-contained | One package per distro, all models bundled. git clone and go. |
How irlume compares to Windows Hello and the Linux face-unlock projects you've probably met (Howdy, visage):
| Windows Hello | Howdy | visage |
irlume | |
|---|---|---|---|---|
| Liveness / anti-spoof | IR only (bypassable — CVE-2021-34466) | ❌ none — its own README warns a "well-printed photo of you could be enough" | ❌ none | ✅ algorithmic IR gate + opt-in passive blink; self-tested vs ISO/IEC 30107-3 |
| Camera-injection defense | device-trust (newer HW) | ❌ none | ❌ none | ✅ device pinning + cross-spectrum RGB↔IR |
| Template protection | TPM-bound enclave | ✅ AES-256-GCM, TPM-sealed key | ||
| Opens your keyring/wallet | ✅ | ❌ (keyring stays locked) | ❌ | ✅ TPM-unseals it at login |
| Stores your face as… | template | encoding | embedding | embedding only, never an image |
| Model licensing | proprietary | MIT code · dlib weights | ✅ permissive, bundleable | |
| Runs on | Windows | Linux | Linux | Linux — Fedora · Arch · Debian/Ubuntu |
v0.1.1. Works end-to-end on real hardware across all three families. Not yet certified (no iBeta lab pass) — see Honest limitations.
You need: x86-64 Linux with systemd & PAM — the three families below are packaged and tested. A TPM 2.0 is strongly recommended (encrypted templates, keyring unlock) but not required. Any camera is fine — it just sets your tier: IR camera → secure login · RGB webcam → screen unlock · fingerprint → companion.
| Fedora | Arch | Debian / Ubuntu |
|---|---|---|
# Copr (signed tags)
sudo dnf copr enable \
archledger/irlume
sudo dnf install irlume |
# prebuilt from Releases
sudo pacman -U \
./irlume-*.pkg.tar.zst |
# .deb from Releases
sudo apt install \
./irlume_*.deb |
Then, once:
irlume ir-setup # IR cameras: enable the 850 nm emitter
irlume tui # enroll your face + configure, guided
sudo irlume login enable --apply # opt-in: wire the greeter + lock screenSafe to try. Installing the package wires nothing into your login —
auth only changes when you run login enable, and without --apply it's a
dry run that prints every PAM edit it would make. Your password always keeps
working, and one command undoes everything: sudo irlume login disable --apply.
irlume update checks for a new release the way your distro expects. Prefer to
build from source? See packaging/ and scripts/install-host.sh.
Privilege-separated by design. The thin pam_irlume.so module and irlume
CLI are untrusted clients of the privileged irlumed daemon — the only thing
that ever touches the camera, IR emitter, models, templates, or TPM. They speak
over a Unix socket authenticated with SO_PEERCRED.
┌───────────────┐ ┌───────────────┐ ╔═══════════════════════════╗
│ pam_irlume.so │ │ irlume (CLI │ ║ irlumed (privileged) ║
│ greeter/sudo │ │ + live TUI) │ ║ ║
└──────┬────────┘ └───────┬───────┘ ║ camera + IR emitter ║
│ SO_PEERCRED │ Unix socket ║ YuNet → AuraFace (ONNX) ║
└────────────────────┴───────────────▶║ IR liveness · matcher ║
║ TPM seal · templates ║
╚═══════════════════════════╝
Model bill-of-materials — every weight is permissive or first-party, all GPLv3-compatible, so the whole thing is bundleable:
| Stage | Model | License |
|---|---|---|
| Detection | YuNet | MIT |
| Recognition | AuraFace (512-D ArcFace) | Apache-2.0 |
| Liveness — IR gate | self-built, algorithmic (no weights) | — |
| Liveness — passive blink | MediaPipe FaceMesh → eye-aspect-ratio (opt-in) | Apache-2.0 |
| IR domain adapter | self-trained (author's own IR captures) | GPL-3.0 |
More depth: Architecture · Threat model · Cross-distro notes.
irlume stores only 512-D embeddings (a one-way projection — you can't rebuild a photo from it), AES-256-GCM encrypted, under a key the TPM seals to your boot state. We audited this live:
- 🧑💻 A normal user account →
catting the files gives Permission denied (root-only, 0600). - 💽 Disk-theft test: copied the encrypted templates and the sealed key to a
second machine with its own TPM →
tpm: integrity check failed. The stolen data is undecryptable off the original box.
Honest delta vs Hello: Hello isolates templates in a VBS/TPM enclave the kernel
never sees; irlume's daemon is a root process holding decrypted embeddings in RAM
during a match — so root on the live machine is the trust boundary (as with
most Linux secrets). Full write-up: docs/SECURITY_AT_REST.md.
Trust is built on candor, so — plainly:
- Passive blink liveness is a deterrent, not a guarantee. It closes casual and typical print/screen attacks, but a determined life-size glossy print still slips through occasionally, and it doesn't cover glasses-wearers (IR lens reflections hide the eyelid). Every miss falls safely to the password. Beating a determined glossy print is the passive-cue ceiling — it needs a trained PAD model or true depth hardware. See ADR-0002 and the PAD self-test results.
- RGB-only laptops get the Convenience tier: face unlocks the screen only —
never
sudo, login, or the keyring (those keep the password). By design. - Not lab-certified. We self-test against ISO/IEC 30107-3; there's no paid iBeta pass. Demographic FMR tuning (FAIRNESS.md) is ongoing.
Is this "Windows Hello for Linux"?
Yes — that's the bar. irlume brings Windows Hello–style face login to Linux:
face-unlock the login screen, lock screen, sudo, and your keyring/wallet,
using the same IR (Windows Hello) camera your laptop already has. And it aims
past Hello where Hello is weak: real anti-spoof liveness, encrypted
TPM-sealed templates, and a fully open stack.
How is irlume different from Howdy?
Howdy is the best-known face unlock for Linux, and it's honest about being a convenience: its README says a well-printed photo could be enough to fool it. irlume is built as an authenticator: an IR liveness gate (self-tested against ISO/IEC 30107-3), AES-256-GCM-encrypted templates under a TPM-sealed key, camera pinning, and TPM keyring unlock at login — with tiers, so RGB-only face match is deliberately limited to screen unlock. See the comparison.
Do I need an IR camera?
No. An IR (Windows Hello) camera gets the full Secure tier — greeter
login, sudo, keyring unlock, works in the dark. A regular RGB webcam
gets the Convenience tier: face unlock for the lock screen only. A
fingerprint reader works as a companion factor on either. All
auto-detected.
Does it work on Ubuntu / Fedora / Arch, GNOME / KDE, Wayland?
Yes — irlume authenticates through PAM, so the desktop stack doesn't matter.
It's validated end-to-end on Fedora (KDE Plasma), Ubuntu (GNOME/GDM), and
Arch, all on Wayland, including the greeter, lock screen, sudo, and
fingerprint paths.
v0.1.1 — working, validated end-to-end on real hardware across Fedora, Arch, and Debian/Ubuntu (IR Secure tier, RGB Convenience tier, and fingerprint). Packaged for all three. Actively hardened; interfaces may still shift before 1.0.
GPL-3.0-or-later — fully open, copyleft: modifications stay free, nobody can lock this down. Contributions welcome under the DCO — no CLA, no commercial relicensing. Security reports: see SECURITY.md.