Configure CachyOS Niri desktop with Noctalia shell
User: aps
OS: CachyOS (Arch-based)
Compositor: Niri (scrolling tiling Wayland)
Desktop Shell: Noctalia (quickshell-based)
Noctalia is a quickshell-based desktop shell that replaces multiple components:
Other tools:
| Component | Config Path |
|---|---|
| Niri | ~/.config/niri/ (modular: config.kdl + cfg/*.kdl) |
| Noctalia | ~/.config/noctalia/settings.json |
| Noctalia Colors | ~/.config/noctalia/colors.json |
| Noctalia Templates | ~/.config/noctalia/user-templates.toml |
| Noctalia User Templates | ~/.config/noctalia/templates/ |
| Ghostty | ~/.config/ghostty/config (generated) |
| Alacritty | ~/.config/alacritty/ |
| Walker | ~/.config/walker/config.toml |
| Fish | ~/.config/fish/config.fish |
| Starship | ~/.config/starship.toml (auto-generated) |
| Themes | ~/.config/themes/ |
| GTK | ~/.config/gtk-3.0/ + ~/.config/gtk-4.0/ |
| Swayidle | ~/.config/swayidle/config |
Noctalia settings: Edit ~/.config/noctalia/settings.json (single 600+ line file)
Niri keybinds: Edit ~/.config/niri/cfg/keybinds.kdl (not main config.kdl)
Theme switching: Use ~/.config/themes/theme-picker.sh (GUI) or manually call Noctalia IPC
Window rules: Edit ~/.config/niri/cfg/rules.kdl
Main Settings: ~/.config/noctalia/settings.json
Current Colors: ~/.config/noctalia/colors.json
Noctalia auto-generates themed configs for: ghostty, alacritty, walker, niri, zed, gtk3/4, btop, cava, zenBrowser, mangoHud, qt, foot, and KDE apps. See the templates.activeTemplates section in settings.json.
User Templates: Enable in Settings → Color Scheme → Templates → Advanced → User templates
~/.config/noctalia/user-templates.toml~/.config/noctalia/templates/# Lock screen
qs -c noctalia-shell --lock
# Launch app launcher
qs -c noctalia-shell --launcher
# Open control center
qs -c noctalia-shell --control-center
# Change wallpaper
qs -c noctalia-shell --set-wallpaper /path/to/wallpaper
# Set color scheme (triggers template regeneration)
qs -c noctalia-shell ipc call colorScheme set <ThemeName>
Config: ~/.config/noctalia/user-templates.toml
Template syntax: {{colors.name.mode.format}}
{{colors.primary.default.hex}}Starship template: ~/.config/noctalia/templates/starship.toml
{{colors.primary.default.hex}} for accent color~/.config/starship.toml on theme changeModular config structure in ~/.config/niri/:
niri/
├── config.kdl # Main entry point
├── cfg/
│ ├── autostart.kdl # Startup apps
│ ├── keybinds.kdl # Keybindings
│ ├── display.kdl # Monitor outputs
│ ├── input.kdl # Keyboard/touchpad
│ ├── layout.kdl # Layout settings
│ ├── rules.kdl # Window rules
│ ├── misc.kdl # Environment variables
│ ├── animation.kdl # Animations
│ └── noctalia.kdl # Noctalia-specific colors
Defined in ~/.config/niri/cfg/autostart.kdl:
qs -c noctalia-shell)Keybinds are defined in ~/.config/niri/cfg/keybinds.kdl. Common binds include terminal, browser, editor, lock screen, and launcher (MOD+Space for Walker theme picker). Check the file for current bindings.
~/.config/themes/
├── themes/ # Theme directories (just need wallpapers/)
│ └── <ThemeName>/
│ └── wallpapers/ # Theme wallpapers (png, jpg, jpeg)
├── theme-picker.sh # Walker-based theme picker (sets scheme + wallpaper)
└── current # Active theme name
Colors: Noctalia generates the color scheme and stores in ~/.config/noctalia/colors.json. All apps (including Starship via user templates) get themed automatically when you change the color scheme.
Wallpapers: Each theme only needs a wallpapers/ directory with image files. The picker selects the first one alphabetically.
Available Themes: 12 themes available (Ayu, Catppuccin, Cherry Blossom, Dracula, Eldritch, Everforest, Gruvbox, Kanagawa, Nord, Osaka jade, Rose Pine, Tokyo Night)
# GUI picker (MOD+Shift+T) - sets Noctalia scheme + wallpaper
~/.config/themes/theme-picker.sh
# Manual theme switch via CLI
qs -c noctalia-shell ipc call colorScheme set <ThemeName>
# Then manually set wallpaper if desired
current fileAll apps update automatically - no manual template substitution needed.
Key Insight: Fingerprint login at greetd doesn't unlock gnome-keyring (needs actual password). We separate PAM configs:
/etc/pam.d/login → includes system-auth → NO fingerprint (requires password for keyring)/etc/pam.d/noctalia-lock → HAS fingerprint (keyring already unlocked)/etc/pam.d/noctalia-lock)#%PAM-1.0
# Noctalia lock screen - includes fingerprint auth
auth sufficient /usr/lib/security/pam_fprintd.so timeout=-1
auth include system-auth
account include system-auth
password include system-auth
session include system-auth
Note: Use full path /usr/lib/security/pam_fprintd.so - Noctalia may not find it otherwise.
Note: timeout=-1 keeps fingerprint reader active indefinitely.
Noctalia reads NOCTALIA_PAM_SERVICE env var to determine which PAM service to use. Set via systemd override:
Override file: ~/.config/systemd/user/noctalia.service.d/pam.conf
[Service]
Environment=NOCTALIA_PAM_SERVICE=noctalia-lock
After creating/editing, run: systemctl --user daemon-reload && systemctl --user restart noctalia.service
Noctalia provides the lock screen with PAM authentication.
Auto-lock: ~/.config/swayidle/config
timeout 120 'qs -c noctalia-shell --lock'
timeout 600 'niri msg action power-off-monitors'
before-sleep 'qs -c noctalia-shell --lock'
Toggle script: ~/.config/swayidle/toggle.sh (MOD+Ctrl+I)
Enroll fingerprints: fprintd-enroll
Result of this setup:
Agent: /usr/lib/polkit-kde-authentication-agent-1
Uses greetd with tuigreet in a minimal sway session.
Config files:
/etc/greetd/config.toml - Main greetd config/etc/greetd/sway-config - Sway session for greeterFeatures: remembers last user/session, shows asterisks for password, displays time, launches niri-session.
Uses wl-clipboard with cliphist for history. Clipboard watching is configured in Noctalia settings.json - look for clipboard-related settings in the appLauncher section.
Edit ~/.config/niri/cfg/keybinds.kdl
Edit ~/.config/niri/cfg/rules.kdl. Example patterns:
window-rule {
match app-id=r#"^firefox$"#
open-maximized true
}
Edit ~/.config/niri/cfg/layout.kdl
pkill walker && walker --gapplication-service &Edit ~/.config/noctalia/settings.json in the bar.widgets.right (or left/center) array. Use CustomButton widget type to add custom buttons with icons, click handlers, and dynamic text from shell commands.
~/.config/noctalia/templates/myapp.conf~/.config/noctalia/user-templates.toml:[templates.myapp]
input_path = "~/.config/noctalia/templates/myapp.conf"
output_path = "~/.config/myapp/theme.conf"
post_hook = "pkill -USR1 myapp" # optional reload command
{{colors.primary.default.hex}}These files are managed automatically - edit their sources instead:
| Generated File | Source/Manager |
|---|---|
ghostty/config | Noctalia template in settings.json |
alacritty/themes/noctalia.toml | Noctalia |
walker/themes/noctalia/style.css | Noctalia |
gtk-3.0/noctalia.css | Noctalia |
gtk-4.0/noctalia.css | Noctalia |
starship.toml | Noctalia user template |
niri/cfg/noctalia.kdl | Noctalia |
Dotfiles tracked at github.com/APS6/nox-config.
Remember: After making changes to any system components that are documented in this skill (themes, auth, keybinds, Noctalia config, etc.), update this skill file to reflect the current state. This ensures the AI has accurate information for future tasks.