Gaze

Installation ​

Choose the installation method that suits your system. When you use the one-line installer, it detects your desktop and configures the matching integration where possible: GNOME lock screen authentication, the Cinnamon extension, KDE packages, or the Omarchy lock integration. On other desktops, it skips desktop-specific packages. Manual GNOME and Cinnamon installs require an extra step to enable the extension.

On x86_64 and arm64, the installer supports Ubuntu 24.04/25.10/26.04/26.10, Debian 13 and 14 (forky, currently testing), Fedora 42/43/44/45 and compatible distributions (including image-based OSTree systems such as Silverblue, Kinoite, and Bazzite), Arch Linux, and Arch-compatible AUR distributions such as Manjaro and CachyOS. openSUSE Tumbleweed is supported on x86_64.

CPU requirement ​

On x86_64, the gazed daemon requires AVX2 (Intel Haswell and newer, roughly 2013 onward; AMD Excavator and newer, roughly 2015 onward). The ONNX Runtime it links issues AVX2 instructions during startup, so on an older CPU the daemon exits immediately rather than running degraded.

Check before installing:

bash
grep -qw avx2 /proc/cpuinfo && echo "AVX2 present" || echo "AVX2 missing"

Gaze's inference runtime needs AVX2 on x86_64. If your CPU does not support it, the one-line installer stops before making system changes; package installs leave gazed stopped, though the CLI and PAM modules are still installed. gaze doctor reports the limitation as well. Face authentication requires a CPU with AVX2; see troubleshooting for details.

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

The installer adds:

  • the Gaze daemon and CLI
  • gaze-gui
  • the GNOME Shell extension package only when a GNOME desktop session is detected
  • the Cinnamon extension package only when a Cinnamon desktop session is detected

The installer also configures package updates where needed and enables the gazed daemon. When supported, it enables lock screen face unlock or PolKit confirmation for your current user.

Desktop integration depends on the session it detects. On KDE Plasma, it installs gaze-kde to wire up the lock screen; on Cinnamon, it installs gaze-cinnamon-extension. For Quickshell Omarchy, it selects gaze-omarchy; see the Omarchy guide for setup instructions and supported versions. Other desktops do not receive desktop extension packages.

On OSTree systems such as Silverblue, Bazzite, and Kinoite, the installer uses rpm-ostree to layer the packages. On openSUSE Tumbleweed, it uses zypper and Gaze's Tumbleweed-specific RPM repository.

Desktop behavior:

  • CLI, GUI, and normal PAM prompts work without desktop extensions.
  • If the installer detects Cinnamon, it installs gaze-cinnamon-extension and enables it for the session.
  • If the installer detects KDE Plasma, it installs gaze-kde alongside the base packages, so the lock screen starts face auth on its own and a Face Unlock entry appears in System Settings.
  • On Quickshell Omarchy, it installs the Gaze lock plugin and enables it from the unlocked desktop user session.
  • If you later want GNOME or Cinnamon lock screen support, install the appropriate extension package manually from your desktop session.
  • GDM loads the extension from package defaults when the extension package is installed, but GDM login face auth stays disabled unless you explicitly enable it.

For non-interactive installs:

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

Path B: manual package install ​

Use this if you prefer to configure package sources yourself. Debian/Ubuntu, Fedora-compatible systems, and openSUSE Tumbleweed use Gundu Labs repositories. Arch Linux and Arch-compatible distributions such as Manjaro and CachyOS use the AUR packages.

Debian/Ubuntu packages are built per release, and each apt suite carries only the builds for that release: noble (Ubuntu 24.04), questing (Ubuntu 25.10), resolute (Ubuntu 26.04), stonking (Ubuntu 26.10), trixie (Debian 13), and forky (Debian 14). The snippet below picks the suite matching your system; installing another release's package leaves gazed unable to load its OpenCV libraries.

Debian 14 (forky) is still testing, so its libraries keep moving. The forky packages are built against whatever OpenCV and GTK sonames testing carried at release time, and a soname bump in testing can leave gazed unable to start until the next Gaze release rebuilds against it. Reinstalling from the forky suite after such a bump picks up the rebuilt package.

If you are replacing an existing manual repository configuration, remove the current repo files first:

Debian / Ubuntu:

bash
sudo rm -f /etc/apt/sources.list.d/gundulabs.list /usr/share/keyrings/gundulabs-archive-keyring.gpg

Fedora and compatible DNF/rpm-ostree systems:

bash
sudo rm -f /etc/yum.repos.d/gundulabs.repo /etc/pki/rpm-gpg/RPM-GPG-KEY-gundulabs

openSUSE Tumbleweed:

bash
sudo rm -f /etc/zypp/repos.d/gundulabs.repo /etc/pki/rpm-gpg/RPM-GPG-KEY-gundulabs
bash
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://packages.gundulabs.com/keys/gundulabs-repo.gpg \
  | sudo tee /usr/share/keyrings/gundulabs-archive-keyring.gpg >/dev/null
suite="$(. /etc/os-release && echo "${VERSION_CODENAME:-$UBUNTU_CODENAME}")"
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gundulabs-archive-keyring.gpg] https://packages.gundulabs.com/deb $suite main" \
  | sudo tee /etc/apt/sources.list.d/gundulabs.list >/dev/null
sudo apt update
sudo apt install gaze gaze-gui
bash
sudo rpm --import https://packages.gundulabs.com/keys/gundulabs-repo.asc
sudo tee /etc/yum.repos.d/gundulabs.repo >/dev/null <<'EOF'
[gundulabs]
name=Gundu Labs
baseurl=https://packages.gundulabs.com/rpm/fedora/$releasever/$basearch
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://packages.gundulabs.com/keys/gundulabs-repo.asc
EOF
sudo dnf makecache
sudo dnf install gaze gaze-gui
bash
sudo tee /etc/yum.repos.d/gundulabs.repo >/dev/null <<'EOF'
[gundulabs]
name=Gundu Labs
baseurl=https://packages.gundulabs.com/rpm/fedora/$releasever/$basearch
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://packages.gundulabs.com/keys/gundulabs-repo.asc
EOF
sudo rpm-ostree install gaze gaze-gui
bash
# Alternative to the Gundu Labs dnf repository above; do not enable both.
# Copr builds and signs these packages on Fedora's own builders.
sudo dnf install dnf-plugins-core
sudo dnf copr enable gundulabs/gaze
sudo dnf install gaze gaze-gui
bash
sudo rpm --import https://packages.gundulabs.com/keys/gundulabs-repo.asc
sudo tee /etc/zypp/repos.d/gundulabs.repo >/dev/null <<'EOF'
[gundulabs]
name=Gundu Labs
baseurl=https://packages.gundulabs.com/rpm/opensuse/tumbleweed/$basearch
enabled=1
autorefresh=1
type=rpm-md
gpgcheck=1
gpgkey=https://packages.gundulabs.com/keys/gundulabs-repo.asc
EOF
sudo zypper refresh
sudo zypper install gaze gaze-gui
bash
# Requires an AUR helper such as yay or paru. yay shown here.
yay -S --needed gaze-bin gaze-gui-bin

The openSUSE RPM ships a pam-config definition and enables Gaze for sudo, GDM, and other services that include common-auth in its post-install script. To reapply the setting manually after changing PAM modules, run:

bash
sudo pam-config --add --gaze
sudo pam-config --update

The one-line installer also reapplies this setting after the package install when pam-config is available.

Arch: install the -bin packages, not the release artifacts

On Arch, install Gaze only through the AUR packages above. The gaze-*.pkg.tar.zst files attached to each GitHub release are the inputs the AUR wrappers unpack, not a supported install path: they carry the plain package names gaze and gaze-gui, and an unrelated AUR package is also named gaze (a file watcher). Installing them with pacman -U leaves a foreign gaze that the next yay -Syu or paru -Syu silently "upgrades" to the unrelated package, removing gazed, the PAM modules, and the systemd unit. See Gaze disappears after an AUR helper upgrade if this already happened to you.

Path C: GUI-only via Flatpak ​

The Flatpak is published to the Gundu Labs repository. The signing key and repo URL are embedded in the .flatpakref, so one command adds the remote and installs the app:

bash
flatpak install --from https://packages.gundulabs.com/flatpak/com.gundulabs.Gaze.flatpakref

This installs the sandboxed Gaze GUI only. It talks to the gazed daemon on the system bus, so you still need to install one of the system packages (Path A or B) for the daemon and PAM integration. Use this path when you want the GUI updated independently of the system package.

Enable GNOME lock screen auth after manual install ​

Only run this on GNOME desktops where you want face unlock from the lock screen. First install the extension package for your distro, then enable it for your user; package managers do not safely change per-user extension settings.

bash
sudo apt install gaze-gnome-extension
bash
sudo dnf install gaze-gnome-extension
bash
sudo zypper install gaze-gnome-extension
bash
yay -S --needed gaze-gnome-extension-bin
bash
gnome-extensions enable gaze@gundulabs.com
gsettings set org.gnome.shell.extensions.gaze enable-face-authentication true

Reboot once after installing or updating the extension if the lock screen does not pick it up immediately. Run the two commands above from a session that started after the package was installed: GNOME Shell drops extension IDs it has not scanned yet, so enabling one from the session you installed in can look right and then be gone after the next logout. See The extension disappears again after a logout.

GDM login face auth stays disabled unless you explicitly enable it; see the GNOME Extension guide before doing that.

KDE Plasma and other PAM-based desktops ​

The one-line installer detects KDE Plasma and intentionally skips gaze-gnome-extension, because that package depends on GNOME Shell. It installs gaze-kde instead, which makes the KDE lock screen start face auth on its own with no key press and adds a Face Unlock entry to System Settings. Keep password fallback enabled while testing.

The KDE login greeter (Plasma Login Manager, or SDDM) is a separate program with no up-front biometric slot upstream, so face auth there starts when you submit the login form, exactly as a fingerprint reader does on the same screen. See the KDE Plasma guide.

For other PAM-based desktops, use the base gaze package's PAM modules and see the PAM guide.

Omarchy Quickshell lock ​

Use the Omarchy guide. The gaze-omarchy package provides independent face, password and fingerprint PAM conversations. After installation, run gaze-omarchy enable without sudo from your unlocked desktop. It supports Omarchy 4.0.2/4.0.3 and checks the shell files before enablement.

Enable face unlock for hyprlock ​

On Hyprland using hyprlock, install the gaze-hyprlock package (auto-installed by the one-line installer when Hyprland is detected) and point hyprlock at the Gaze PAM service. See the Hyprland guide.

Path D: Nix and NixOS ​

Gaze ships a Nix flake with packages and a NixOS module that sets up the daemon, D-Bus/polkit policies, and PAM declaratively:

nix
# flake.nix inputs
inputs.gaze.url = "github:GunduLabs/gaze";
nix
# NixOS configuration
imports = [ inputs.gaze.nixosModules.default ];
services.gaze = {
  enable = true;
  gui.enable = true;
};

On non-NixOS systems with Nix or home-manager you can install the CLI and GUI from the flake, but the daemon and PAM integration still need a system package (Path A or B). See the Nix & NixOS guide for module options, GNOME/hyprlock integration, and home-manager usage.

Restart after install ​

After installing Gaze by any method, reboot once to apply all system-level changes.

bash
sudo reboot

Verify installation ​

bash
systemctl status gazed
gaze --version
gaze doctor
gaze-gui --help

Run gaze doctor as your desktop user. This lets it inspect your PipeWire session and desktop integration.

If the daemon is inactive, start and enable it with:

bash
sudo systemctl enable --now gazed

First run ​

bash
gaze add-face default
gaze auth --verbose

Development and source builds ​

See the Development guide for source builds, tests, packaging, and Flatpak development workflows.