Quick Start

Package Install

Arch Linux (AUR)

yay -S facelock           # or paru -S facelock

Debian / Ubuntu (APT)

For modern systems (Debian trixie+, Ubuntu 25.04+) with TPM support:

# Add signing key
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://tysmith.me/facelock/apt/tysmith-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/tysmith-archive-keyring.gpg >/dev/null

# Add repository (main = TPM enabled)
echo "deb [signed-by=/etc/apt/keyrings/tysmith-archive-keyring.gpg] https://tysmith.me/facelock/apt main facelock" \
  | sudo tee /etc/apt/sources.list.d/facelock.list

# Install
sudo apt update
sudo apt install facelock

For older systems (Ubuntu 24.04, Debian bookworm) without TPM:

# Add signing key (same as above)
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://tysmith.me/facelock/apt/tysmith-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/tysmith-archive-keyring.gpg >/dev/null

# Add repository (legacy = non-TPM)
echo "deb [signed-by=/etc/apt/keyrings/tysmith-archive-keyring.gpg] https://tysmith.me/facelock/apt legacy facelock" \
  | sudo tee /etc/apt/sources.list.d/facelock.list

# Install
sudo apt update
sudo apt install facelock

Fedora / RHEL (COPR)

sudo dnf copr enable tyvsmith/facelock
sudo dnf install facelock

Post-Install

sudo facelock setup       # download models, configure PAM
sudo facelock enroll      # register your face
sudo facelock test        # verify recognition

Prerequisites (Building from Source)

• Rust 1.85+ (rustup update)
• just task runner
• Linux with V4L2 support
• System dependencies: libv4l-dev libpam0g-dev clang (Debian/Ubuntu) or v4l-utils pam clang (Arch)
• A webcam (IR recommended for production; RGB works for development)

Development Setup

1. Build

just build

2. Download Models and Enroll

sudo facelock setup     # interactive wizard (camera, models, encryption)
sudo facelock enroll    # capture your face (look at camera)
sudo facelock test      # verify recognition works

No daemon needed -- the CLI auto-falls back to direct mode when no daemon is running.

3. Explore

sudo facelock devices            # list cameras
sudo facelock list               # see enrolled models
sudo facelock preview --text-only  # live detection output
sudo facelock status             # check system status
sudo facelock bench warm-auth    # measure auth latency

4. Run Tests

just check                # unit tests + clippy + fmt
just test-pam             # container PAM smoke tests (no camera)
just test-integration     # end-to-end with camera (daemon mode)
just test-oneshot         # end-to-end with camera (no daemon)
just test-shell           # interactive container shell

System Installation

A broken PAM module can lock you out. Keep a root shell open until you've verified face auth works. See the Testing chapter for details.

Install

just install              # build release + install everything
sudo facelock setup       # download models
sudo facelock enroll      # register your face

This installs the binary, PAM module, systemd service, D-Bus policy, and adds face auth to /etc/pam.d/sudo.

Verify

Open a new terminal and run:

sudo echo "face auth works"

You should see "Identifying face..." and authenticate by looking at the camera.

GPU Acceleration (Optional)

GPU support is runtime-only -- no special build flags needed. The setup wizard (facelock setup) offers CPU or CUDA selection and warns if dependencies are missing.

For manual configuration, install a GPU-enabled ONNX Runtime package:

sudo pacman -S onnxruntime-opt-cuda      # NVIDIA
sudo pacman -S onnxruntime-opt-rocm      # AMD
sudo pacman -S onnxruntime-opt-openvino  # Intel

Set execution_provider in /etc/facelock/config.toml to "cuda", "rocm", or "openvino". CPU is the default.

Uninstall

just uninstall

Config and data are preserved in /etc/facelock and /var/lib/facelock. To remove everything:

sudo rm -rf /etc/facelock /var/lib/facelock /var/log/facelock

Configuration

Config file: /etc/facelock/config.toml (installed) or config/facelock.toml (source).

Key settings:

Full reference: config/facelock.toml (all keys documented with comments).