ja
ee592cc21b
Hyprland 0.53+ requires launching via start-hyprland (watchdog) for proper crash diagnostics and signal handling. Without it a warning banner appears on login. Override package-managed hyprland.desktop with local copy pointing to start-hyprland. XDG_DATA_DIRS priority ensures the override wins without modifying system files. - ansible/roles/hyprland/tasks/main.yml: manage override in ~/.local/share/wayland-sessions/ - docs/adr/0004-start-hyprland-override.md: full decision record - docs/hyprland-uwsm.md: document override behavior
2.9 KiB
Hyprland Configuration - uwsm Integration
Architecture
Session management uses UWSM (Universal Wayland Session Manager) wrapping Hyprland in systemd user services.
greetd → tuigreet → uwsm start → systemd user session → Hyprland
↓
systemd units: hyprpaper, waybar, dunst, hypridle, hyprlauncher, cliphist
XDG autostart: Nextcloud, JetBrains Toolbox, Flameshot, etc.
Session Services
All session services are managed via systemd user units (~/.config/systemd/user/*.service):
| Service | Purpose | Status |
|---|---|---|
hyprpaper.service |
Wallpaper daemon | active |
waybar.service |
Status bar | active |
dunst.service |
Notification daemon | active |
hypridle.service |
Idle/screenlock control | active |
hyprlauncher.service |
App launcher daemon | active |
cliphist.service |
Clipboard history store | active |
Management Commands
# Check all session services
systemctl --user list-units | grep -E 'hypr|waybar|dunst|cliphist'
# Restart a specific service
systemctl --user restart waybar.service
# View logs
journalctl --user -u waybar.service -f
Launchers
| Component | Tool | Keybind |
|---|---|---|
| App Launcher | hyprlauncher | SUPER+D |
| Keybind Menu | hyprlauncher -o (piped) | SUPER+CTRL+K |
hypr launcher config: ~/.config/hypr/hyprlauncher.conf
desktop_launch_prefix = uwsm app --(proper systemd scoping)- Cache enabled for frequency-based sorting
- Finders: desktop (default), math (=), unicode (.), font (')
Login Manager
greetd with tuigreet on VT 1.
Config: /etc/greetd/config.toml
Default command: tuigreet --time --remember --asterisks --cmd 'uwsm start -e -D Hyprland hyprland.desktop'
Wayland Session Override (start-hyprland)
The package provides /usr/share/wayland-sessions/hyprland.desktop with
Exec=Hyprland (direct binary), but Hyprland 0.53+ requires launching through
start-hyprland (watchdog parent process) for crash diagnostics and proper
signal handling. Otherwise a warning banner appears on login.
A local override at ~/.local/share/wayland-sessions/hyprland.desktop sets
Exec=start-hyprland, which uwsm then manages inside the systemd session.
XDG_DATA_DIRS priority ensures the override wins without touching system files.
Managed by Ansible role hyprland — see docs/adr/0004-start-hyprland-override.md.
Key Categories
| Category | Modifier | Keys | Action |
|---|---|---|---|
| Focus | SUPER | H/J/K/L, Arrows | Move focus |
| Move Window | SUPER+SHIFT | H/J/K/L, Arrows | Move window |
| Resize Window | SUPER+ALT | H/J/K/L | Resize active window |
| Windows | SUPER | F, SPACE, TAB, `, P, J | Window actions |
| Apps | SUPER | Q, B, E, D | Launch apps |
| Workspaces | SUPER | 1-9 | Switch/move workspaces |
| Lock | SUPER+CTRL | L | Lock screen |
See ~/.config/hypr/cheatsheet.txt for the full reference.