Gaze

GUI Guide ​

On KDE Plasma

gaze-kde adds a Face Unlock entry to System Settings that opens this app. See the KDE Plasma guide.

Use gaze-gui to enroll your face, test recognition, and adjust Gaze settings.

Launch it:

bash
gaze-gui
  • Enroll a face: Follow the camera prompts. If both RGB and IR cameras are configured, Gaze captures from both.
  • View profiles: The main window lists enrolled faces, their total template counts, and RGB and IR badges. A badge is green when the profile has captures for that spectrum, amber when a camera is configured but the profile has no captures, and grey when no camera is configured. An RGB-only machine therefore shows a green RGB badge and a grey IR badge; grey does not indicate a failure.
  • Refine a profile: Select its edit/refine icon to capture additional samples or add a missing spectrum. For example, you can add IR captures to an RGB-only profile after configuring an IR camera.
  • Test authentication: Run a face scan to check whether Gaze recognizes you.
  • Remove profiles: Delete individual face profiles.
  • Change daemon settings: Adjust the security level, cameras, liveness settings, and hybrid policy.

Configuration dialog ​

Open the config dialog from the header-bar settings button.

The dialog mirrors /etc/gaze/config.toml, grouped the same way. Saving writes the file through the daemon, so it needs a polkit authorization.

Security

  • Security level (low, medium, high, maximum, or custom)
  • For custom: detector level, recognizer level, RGB and IR similarity thresholds

Hardware

  • Inference execution provider: CPU, automatic NPU selection, Intel OpenVINO, or AMD Vitis AI
  • OpenVINO inference device; automatic and AMD modes select NPU

The standard build exposes all providers. Install the vendor runtime and drivers using Hardware Acceleration, then restart the daemon after changing its provider.

Cameras

  • RGB camera source, IR camera source, and Force IR Emitter
  • Parallel RGB + IR Capture, which decides whether hybrid verification reads both sensors at once. Some webcams cannot, so the default captures them one at a time
  • Darkness cutoff, the dark-frame rejection threshold

Enrollment

  • Max templates per face
  • Minimum face size ratio, where lower values allow enrollment from farther away

Liveness Anti-Spoofing

  • Enable liveness spoof prevention, liveness threshold, liveness max seconds

Auth

  • Abort if SSH, abort if lid closed
  • Require a suspend first, which refuses face auth until the machine has suspended and resumed once
  • Require confirmation on lock screen, require confirmation for elevated auth
  • Resume grace period and start delay, both in milliseconds
  • Start delay applies to, either every face auth or screen lockers only
  • Hybrid combining policy, used when both RGB and IR are enrolled

Storage

  • Encrypt face templates, which seals enrolled templates with the TPM. See How it works for what that protects against.
  • Unlock GNOME Keyring, which replays an enrolled password after a liveness-protected GDM or greetd face login. It needs template encryption and liveness on, and each user still has to run gaze keyring. Read what it changes about your security first.

Common tasks ​

  1. Enroll a profile named default.
  2. Run test authentication several times in normal room light.
  3. Add another profile if your appearance varies often (for example, glasses).

When to use GUI vs CLI ​

  • Use GUI for enrollment and quick pass/fail checks.
  • Use CLI (gaze auth --verbose) when you want detailed authentication metrics and diagnostics.

If the GUI cannot authenticate ​

Check daemon status:

bash
systemctl status gazed

If the service is stopped, enable and start it:

bash
sudo systemctl enable --now gazed

Then retry from GUI.