Hyprland on Gentoo: Wayland Done Right

It’s 2 AM and my Super key doesn’t work.

I’m running Hyprland on Gentoo—a combination that’s either brave or stupid, depending on who you ask. Everything else is perfect. Three monitors configured. Workspaces bound to each display. Waybar showing per-monitor workspace indicators. The config I’ve been building for weeks is finally coming together.

And then I press Super+D to launch an app and… nothing happens.

This is the story of setting up Wayland’s most interesting tiling compositor on a distro that makes you work for everything—and the dumbest bug I’ve ever spent two hours debugging.

The Setup

My desktop runs Argo OS, my custom Gentoo-based system with OpenRC (not systemd). Most Hyprland documentation assumes Arch with systemd. Every guide starts with systemctl --user enable this or journalctl -xe that. On OpenRC, you get to figure out the equivalents yourself.

The hardware:

  • Three monitors (HDMI-A-1 left, DP-2 center, DP-1 right)
  • NVIDIA RTX 4070 Ti (yes, on Wayland—it works better than you’d think in 2025)
  • Logitech G915 wireless keyboard

My Hyprland config lives at ~/.config/hypr/hyprland.conf, and I have KDE Plasma installed as a fallback on a separate TTY. This lets me edit configs in Kate while testing changes in Hyprland—logout from Plasma, Ctrl+Alt+F3 to Hyprland, test, Ctrl+Alt+F7 back to Plasma if something breaks.

The Super Key Mystery

Everything worked except key bindings involving the Super (Windows) key. No launcher. No window movement. No workspace switching. The modifier was simply… gone.

First instinct: check the config.

grep -i "mainmod\|super" ~/.config/hypr/hyprland.conf
$mainMod = SUPER
bind = $mainMod, RETURN, exec, kitty
bind = $mainMod, Q, killactive
bind = $mainMod, D, exec, rofi -show drun

Config looked fine. Time to check if Wayland was even seeing the key.

Enter wev

On Wayland, the diagnostic tool is wev—the Wayland equivalent of xev. On Gentoo, it required unmasking:

echo "gui-apps/wev ~amd64" | sudo tee -a /etc/portage/package.accept_keywords/wev
emerge --usepkgonly --getbinpkg gui-apps/wev

Ran wev, clicked the window to give it focus, pressed Super…

Nothing.

Not a single event. Every other key registered. Super was invisible.

Going Deeper

When wev shows nothing, either the key isn’t being detected by Wayland, or something’s intercepting it before Wayland sees it. Time to check at kernel level.

sudo showkey -k
kb mode was ?UNKNOWN?
press any key (program terminates 10s after last keypress)...

Pressed Super. Still nothing. Pressed other keys—Enter, Shift, random letters—all showed keycodes. Super was being eaten somewhere between the keyboard and the kernel.

That narrowed it down considerably.

The Dumbest Bug

Logitech G915. Gaming keyboard. Gaming mode.

I’d completely forgotten this keyboard has a dedicated gaming mode button near the top right. When enabled, it disables the Windows key to prevent accidental game minimization. I’d apparently bumped it at some point and never noticed because I was in Plasma using mouse-driven workflows.

One button press. Gaming mode disabled.

wev
[14: wl_keyboard] key: serial: 48372; time: 234789; key: 125; state: 1 (pressed)
sym: Super_L (65515), utf8: ''

Two hours of debugging. One toggle switch.

The Kitty Problem

With Super working, I immediately hit another issue. Pressing Super+Shift+C to copy in Kitty terminal produced 9;10u instead of copying text.

Kitty’s enhanced keyboard protocol conflicts with some Hyprland key bindings. The terminal was interpreting the key combo differently than Hyprland expected. The fix:

echo "keyboard_protocol none" >> ~/.config/kitty/kitty.conf

Restart Kitty, and copy/paste works normally again.

Waybar: The Status Bar

Once keybindings worked, I spent the next several hours on Waybar—the status bar that replaces i3bar, polybar, or whatever you used on X11. Waybar’s configuration is JSON plus CSS, which sounds horrible but actually makes theming straightforward.

My config shows per-monitor workspaces:

{
    "layer": "top",
    "height": 26,
    "modules-left": ["hyprland/workspaces"],
    "modules-center": ["clock"],
    "modules-right": ["cpu", "memory", "pulseaudio", "network"],

    "hyprland/workspaces": {
        "format": "{icon}",
        "on-click": "activate"
    }
}

The key insight: Waybar only runs under Hyprland, not Plasma. If you’re editing configs in Plasma and wondering why nothing shows up—that’s why.

To reload after changes:

killall waybar && waybar &

Or add it to exec-once in your Hyprland config:

exec-once = waybar

HyprLuna: Stealing Ideas

Rather than building everything from scratch, I cloned HyprLuna to study their modular config structure. Their setup splits configs across multiple files:

~/.config/hypr/hyprland/
├── animations/
│   ├── Lunaric.conf
│   ├── animations-dynamic.conf
│   └── animations-minimal-1.conf
├── decorations/
│   └── default.conf
├── keybinds/
│   └── default.conf
└── env/
    └── nvidia.conf

This modular approach is cleaner than one massive config file. You can swap animation styles by changing a single source line:

source = ~/.config/hypr/hyprland/animations/Lunaric.conf

I cherry-picked their bezier curves for smoother animations:

bezier = overshot, 0.05, 0.9, 0.1, 1.05
bezier = smoothOut, 0.36, 0, 0.66, -0.56
bezier = smoothIn, 0.25, 1, 0.5, 1

animation = windows, 1, 5, overshot, slide
animation = windowsOut, 1, 4, smoothOut, slide
animation = border, 1, 10, default
animation = fade, 1, 5, smoothIn
animation = workspaces, 1, 6, overshot, slidevert

The difference is night and day. Windows glide instead of snap. Workspaces slide vertically with a satisfying overshoot.

OpenRC Integration

Here’s the unique part about running Hyprland on Gentoo with OpenRC. There’s no systemctl --user to manage user services. I start Hyprland from a simple wrapper script:

#!/bin/bash
export XDG_CURRENT_DESKTOP=Hyprland
export QT_QPA_PLATFORM=wayland
export MOZ_ENABLE_WAYLAND=1
exec Hyprland

This goes in ~/.local/bin/start-hyprland.sh and gets called from .bash_profile when I want to start it from TTY. Or I select it from SDDM at the login screen.

For services that need to run in the Hyprland session, exec-once handles it:

exec-once = waybar
exec-once = dunst
exec-once = /usr/lib/polkit-kde-authentication-agent-1

No systemd user units required.

The Workspace Layout

My final workspace assignment:

# Left monitor (HDMI-A-1): workspaces 1-3
workspace = 1, monitor:HDMI-A-1, default:true
workspace = 2, monitor:HDMI-A-1
workspace = 3, monitor:HDMI-A-1

# Center monitor (DP-2): workspaces 4-6
workspace = 4, monitor:DP-2, default:true
workspace = 5, monitor:DP-2
workspace = 6, monitor:DP-2

# Right monitor (DP-1): workspaces 7-9
workspace = 7, monitor:DP-1, default:true
workspace = 8, monitor:DP-1
workspace = 9, monitor:DP-1

Super+1 through 9 switches workspaces. Super+Shift+1-9 moves windows. Each monitor has its own set, no overlap.

The Lessons

Check the obvious first. I went straight to kernel-level debugging when the problem was a physical toggle switch on my keyboard. The G915’s gaming mode light was probably on the whole time—I just didn’t think to look.

Wayland diagnostic tools matter. wev is essential. On Gentoo, you might need to unmask it. Do it anyway.

Kitty’s keyboard protocol conflicts. If you get weird character output instead of key bindings working, try keyboard_protocol none in kitty.conf.

Modular configs scale better. Sourcing separate files for animations, decorations, and keybinds keeps things manageable. Steal ideas from projects like HyprLuna.

OpenRC works fine. You don’t need systemd for Hyprland. The init system doesn’t matter once your session is running—just handle autostart with exec-once.

What I’d Do Differently

Start with wev immediately for any input issues. I should have tested the Super key in a diagnostic tool before assuming it was a config problem.

I’d also commit my config to git from day one. Version control for dotfiles would have saved me multiple times when I broke something during the Waybar experiments.

Where This Goes

Hyprland on Gentoo with OpenRC is surprisingly stable once configured. The combination gives you Wayland’s modern protocol with Gentoo’s control over your entire system stack. No systemd dependency. No binary distribution assumptions.

The three-monitor setup with per-monitor workspaces is exactly what I wanted from a tiling compositor. After years of KDE, having windows tile automatically and workspaces that actually work the way I think they should—it’s worth the setup time.

Even if some of that time was spent debugging a keyboard button I forgot existed.

The Logitech G915 gaming mode light is now burned into my memory. I check it first when anything involving Super breaks.