Gaze

Getting Started ​

Get Gaze running in under 10 minutes: install, enroll your face, and verify authentication.

Before you begin ​

  • Linux desktop with a working PipeWire/GStreamer webcam
  • sudo access
  • Internet connection for first-time model download

Step 1: Install Gaze ​

Recommended one-line installer:

bash
curl -fsSL https://gaze.gundulabs.com/install.sh | sh

If you prefer manual package setup, use the installation guide.

Step 2: Check daemon status ​

bash
systemctl status gazed

If it is not running:

bash
sudo systemctl enable --now gazed

Step 3: Enroll your first face ​

bash
gaze add-face default

Tips while enrolling:

  • Keep your face centered and well lit.
  • Face the camera naturally for the first capture; the remaining direction prompts are measured relative to that pose.
  • Use small, deliberate movements and hold each prompted angle still.
  • Remove strong backlight if possible.

Step 4: Test authentication ​

bash
gaze auth

For extra details:

bash
gaze auth --verbose

Step 5: Open the GUI (optional) ​

bash
gaze-gui

Use the GUI to enroll additional face profiles (for example, with glasses and without glasses).

Step 6: Verify GNOME lock screen auth (optional) ​

Only do this on GNOME if you want face unlock from the lock screen. The one-line installer enables the extension for the current GNOME user when possible. If you installed packages manually or the installer could not enable it automatically, run:

bash
gnome-extensions enable gaze@gundulabs.com
gsettings set org.gnome.shell.extensions.gaze enable-face-authentication true

Run those from a GNOME session that started after the package was installed. GNOME Shell only scans extension directories at session start and drops IDs it does not recognise, so enabling the extension from the session you installed in can look correct and then vanish at the next logout. Reboot, then re-run the two commands. gaze doctor reports this as GNOME extension: installed, but not enabled for the current user and prints the same steps. See The extension disappears again after a logout.

Hands-free lock screen and GDM login face auth through this extension are GNOME-specific. KDE Plasma gets a hands-free lock screen a different way, through the biometric PAM slot KScreenLocker starts up front, see KDE Plasma. Other desktops integrate the lock screen through PAM instead, see Hyprland and PAM. GDM login face auth is separate and disabled by default due to GNOME keyring behavior. See GNOME Extension for details and optional login enablement.

If something fails ​

Go to the troubleshooting guide for camera, daemon, PAM, and low-match issues.

Next ​