Warning: This is a vibe coded project. Precautions were taken and code was checked, however be warned.

I have always wanted to make an AMD compatible howdy that ran on the GPU, but upstream dlib refused to add support for ROCm.

So I took matters into my own hands.

howy is a Linux face authentication daemon -- a drop-in replacement for howdy, written in Rust. It aims to solve the biggest pain points:

1. AMD GPU support -- Natively supports MIGraphX via ONNX Runtime. The ROCm stack is still finnicky, but it works. Falls back to CPU if GPU isn't available.
2. Daemon architecture -- Models stay warm and loaded in memory. No more cold-starting a CNN on every sudo like howdy does. Auth typically completes in ~500ms.
3. [WIP] Proper enrollment flow -- Apple FaceID-style pose-guided enrollment with MediaPipe face tracking. Captures multiple angles for better recognition.

pam_howy.so  ──┐
howy CLI     ──┼──  Unix socket  ──  howyd (daemon)
enroll.py    ──┘                      ├── SCRFD (face detection)
                                      ├── ArcFace (face recognition)
                                      └── ONNX Runtime (MIGraphX/CUDA/CPU)

• howyd: Daemon that preloads ONNX models (SCRFD + ArcFace), keeps them hot, and cold-opens the camera only during auth/enrollment.
• pam_howy.so: Thin PAM module that connects to the daemon via Unix socket. Panic-safe, falls back gracefully.
• howy: CLI for managing face models (add, enroll-batch, list, remove, clear, test, doctor, prewarm).
• enroll.py: Python frontend for pose-guided enrollment capture (runs via uv).

The provider = "auto" config tries GPU providers in order and caches the first one that works. Persistent .mxr cache eliminates MIGraphX compilation on subsequent boots.

• Rust toolchain
• OpenCV 4.x (system package)
• ONNX Runtime (system package, e.g. onnxruntime-opt-rocm on Arch)
• SCRFD and ArcFace ONNX models in /usr/share/howy/onnx-data/
• IR camera (or any V4L2 camera)

# Build
ORT_LIB_PATH=/usr/lib ORT_PREFER_DYNAMIC_LINK=1 cargo build --release

# Install (as root)
sudo scripts/install-local.sh

# Prewarm GPU cache (optional, recommended)
sudo howy prewarm

# Check deployment
howy doctor

# Capture frames with pose guidance
uv run scripts/enroll.py --device /dev/video2 --user $USER --label default

# Enroll the captured frames
sudo howy enroll-batch --user $USER --session-dir /tmp/howy-enroll-XXXXX --label default --delete-on-success

# Test authentication
sudo howy test --user $USER

howy is designed as a drop-in replacement for howdy. The install script backs up pam_howdy.so and symlinks it to pam_howy.so, so existing PAM configurations work without modification.

crates/
  howy-common/    # Shared types, config, IPC, face models
  howy-daemon/    # Daemon: inference, camera, server
  howy-pam/       # PAM module (cdylib)
  howy-cli/       # CLI tool
scripts/
  enroll.py       # Pose-guided enrollment frontend
  install-local.sh
  uninstall-local.sh
  download-models.sh
proto/
  howy.proto      # IPC schema (protobuf)
systemd/
  howy.service    # Systemd service unit
  howy.socket     # Systemd socket unit
docs/
  ENROLLMENT_DESIGN.md
  MIGRAPHX_DEPLOYMENT_NOTES.md

GPL-2.0. See LICENSE.