Skip to content

Installation

Prerequisites

  • Linux kernel (x86_64)
  • Wayland compositor with layer-shell support, or gamescope (Steam Gaming Mode)
  • z13ctl installed and daemon running

Runtime dependencies

z13gui links dynamically against GTK 4 and gtk4-layer-shell. The AUR package pulls these automatically; for other install methods, install them via your system package manager first.

Dependency Arch Debian / Ubuntu Fedora
GTK 4 gtk4 libgtk-4-1 gtk4
gtk4-layer-shell gtk4-layer-shell libgtk4-layer-shell0 gtk4-layer-shell

Install

Install the runtime dependencies for your distro, then download the latest linux_amd64 archive from the Releases page:

tar xzf z13gui_*_linux_amd64.tar.gz
sudo install -Dm755 z13gui /usr/local/bin/z13gui

Install the systemd user service:

install -Dm644 contrib/z13gui.service \
    ~/.config/systemd/user/z13gui.service
systemctl --user daemon-reload
systemctl --user enable --now z13gui

Optionally install the desktop entry:

install -Dm644 contrib/z13gui.desktop \
    ~/.local/share/applications/z13gui.desktop

Install the z13gui-bin package with your preferred AUR helper:

yay -S z13gui-bin

The package installs the binary, systemd service, udev rules, and desktop entry. Services are enabled automatically for all users on next login.

Alternatively, download the .pkg.tar.zst package directly from the Releases page and install with pacman:

sudo pacman -U z13gui-*.pkg.tar.zst

Download the .deb package from the Releases page, then install:

sudo apt install ./z13gui_*.deb

The package installs the binary, systemd service, udev rules, and desktop entry. After installing, enable the service:

systemctl --user enable --now z13gui

Download the .rpm package from the Releases page, then install:

sudo dnf install ./z13gui_*.rpm

The package installs the binary, systemd service, udev rules, and desktop entry. After installing, enable the service:

systemctl --user enable --now z13gui

Requires Go 1.23+, CGO enabled, and GTK4 development libraries.

Arch Linux:

sudo pacman -S gtk4 gtk4-layer-shell

Debian/Ubuntu:

sudo apt-get install -y libgtk-4-dev libgtk4-layer-shell-dev

Fedora:

sudo dnf install gtk4-devel gtk4-layer-shell-devel

Then clone and build:

git clone https://github.com/dahui/z13gui
cd z13gui
make build
sudo make install
make install-service

Gamepad input blocking (capabilities)

In Steam Gaming Mode (gamescope), z13gui suppresses controller input while the drawer is open so button presses navigate the overlay instead of the game.

z13gui supports two blocking methods and selects the best one automatically:

Method Requires Behaviour Side effects
BPF blocker (preferred) CAP_BPF + CAP_PERFMON on the binary Blocks PS / Nintendo controller reads at the kernel level via a BPF LSM hook None — Steam and the game keep running normally
SIGSTOP fallback No extra capabilities Pauses the Steam process with SIGSTOP / SIGCONT Game also pauses; PipeWire frame delivery stops

The AUR, .deb, and .rpm packages grant the required capabilities automatically during installation. If you installed from source or from the release binary, grant them manually:

sudo setcap cap_bpf,cap_perfmon+ep /usr/local/bin/z13gui
What are these capabilities and are they safe?

Short version

These two capabilities let z13gui load a tiny kernel filter that tells the system "when Steam tries to read a PS or Nintendo controller, return a temporary 'try again later' error instead." That's all it does. It cannot access your files, network, or any other part of the system. The filter is automatically removed when z13gui exits.

Technical details

CAP_BPF allows loading BPF programs into the kernel. z13gui uses this to attach a single LSM (lsm/file_permission) hook that intercepts read() calls on hidraw character devices (/dev/hidraw*). The hook checks whether the calling PID is in a small allow-list map and the target device is a hidraw device (major 244). If both conditions match, it returns -EAGAIN; otherwise it returns 0 (allow).

CAP_PERFMON is required by the kernel to attach BPF LSM programs. z13gui does not use performance monitoring — this capability is a kernel-imposed prerequisite for LSM attachment.

What the BPF program can do:

  • Return -EAGAIN for read() calls on hidraw devices by specific PIDs
  • Nothing else — the program is verified by the kernel's BPF verifier before loading and cannot be modified at runtime

What the BPF program cannot do:

  • Access files, network, or memory outside its own BPF maps
  • Survive a process exit — all BPF resources are released when z13gui stops, crashes, or is killed
  • Affect any process not explicitly added to its PID map
  • Block any operation other than read() on hidraw devices

Compared to running as root: file capabilities grant only the two listed privileges to the z13gui binary. The process runs as your normal user with no other elevated access. This is strictly safer than running with sudo or as root.

Verify the installation

z13gui --version

Then press the Armoury Crate button on your Z13. The drawer should slide in from the right edge of the screen.

Uninstall

Stop and remove the service:

make uninstall-service

Or manually:

systemctl --user disable --now z13gui
rm -f ~/.config/systemd/user/z13gui.service
systemctl --user daemon-reload

Remove the binary:

sudo rm /usr/local/bin/z13gui

Troubleshooting

Drawer doesn't appear

Make sure the z13ctl daemon is running:

systemctl --user status z13ctl.service

Service fails to start

Check the journal:

journalctl --user -u z13gui -n 50

Run with debug logging to see GTK and initialization output:

z13gui --debug

Gamescope: controller input not suppressed while drawer is open

Grant BPF capabilities so z13gui can block controller input at the kernel level:

sudo setcap cap_bpf,cap_perfmon+ep /usr/local/bin/z13gui

Without capabilities, z13gui falls back to freezing Steam (SIGSTOP), which also pauses running games.

Gamescope: drawer doesn't show

Verify GAMESCOPE_WAYLAND_DISPLAY is set and the socket exists:

echo $GAMESCOPE_WAYLAND_DISPLAY
ls "$XDG_RUNTIME_DIR/$GAMESCOPE_WAYLAND_DISPLAY"

If the socket is missing (stale environment from a previous Gaming Mode session), z13gui automatically falls back to Wayland layer-shell mode.