Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
---
|
|
type: reference
|
|
title: Noctalia Shell
|
|
description: Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls.
|
|
tags:
|
|
- noctalia
|
|
- quickshell
|
|
- wayland
|
|
- shell
|
|
- launcher
|
|
timestamp: 2026-08-06
|
|
---
|
|
|
|
# Noctalia Shell
|
|
|
|
Noctalia Shell is a sleek, minimal desktop shell for Wayland built with [Quickshell](https://github.com/outfoxxed/quickshell). It provides an app launcher, wallpaper manager, session menu, lock screen, hotkey overlay, media controls, and brightness/volume controls.
|
|
|
|
**Version:** 4.7.7
|
|
**Dependency:** noctalia-qs / qs 0.0.12
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
Noctalia communicates through an IPC system accessed via the `qs` command:
|
|
|
|
```bash
|
|
qs -c noctalia-shell ipc call <module> <action> [params]
|
|
```
|
|
|
|
## Components
|
|
|
|
| Component | IPC Command | Description |
|
|
|-----------|-------------|-------------|
|
|
| **Shell** | `qs -c noctalia-shell` | Main shell process |
|
|
| **Launcher** | `ipc call launcher toggle` | Application launcher |
|
|
| **Lock Screen** | `ipc call lockScreen lock` | Screen locker |
|
|
| **Session Menu** | `ipc call sessionMenu toggle` | Power/logout menu |
|
|
| **Hotkey Overlay** | `ipc call overlay toggle` | Visual keybind reference |
|
|
| **Volume** | `ipc call volume increase/decrease/muteOutput` | Audio controls |
|
|
| **Media** | `ipc call media playPause/next/previous` | Media playback |
|
|
| **Brightness** | `ipc call brightness increase/decrease` | Display brightness |
|
|
| **Wallpaper** | Layer namespace `noctalia-wallpaper*` | Desktop wallpaper |
|
|
|
|
---
|
|
|
|
## Niri Integration
|
|
|
|
Noctalia is deeply integrated with the Niri compositor configuration:
|
|
|
|
### Autostart
|
|
|
|
**File:** `~/.config/niri/cfg/autostart.kdl`
|
|
|
|
```kdl
|
|
spawn-sh-at-startup "qs -c noctalia-shell"
|
|
```
|
|
|
|
### Keybindings
|
|
|
|
**File:** `~/.config/niri/cfg/keybinds.kdl`
|
|
|
|
| Keybind | Action | IPC Command |
|
|
|---------|--------|-------------|
|
|
| `Mod+Return` | Terminal | `spawn "ghostty"` |
|
|
| `Mod+CTRL+Return` | App Launcher | `noctalia-shell ipc call launcher toggle` |
|
|
| `Mod+B` | Browser | `spawn "firefox"` |
|
|
| `Mod+ALT+L` | Lock Screen | `noctalia-shell ipc call lockScreen lock` |
|
|
| `Mod+Shift+Q` | Session Menu | `noctalia-shell ipc call sessionMenu toggle` |
|
|
| `Mod+Shift+Escape` | Hotkey Overlay | `show-hotkey-overlay` |
|
|
| `Mod+E` | File Manager | `spawn "nautilus"` |
|
|
|
|
### Media and Brightness
|
|
|
|
| Key | Action | IPC Command |
|
|
|-----|--------|-------------|
|
|
| `XF86AudioRaiseVolume` | Volume Up | `volume increase` |
|
|
| `XF86AudioLowerVolume` | Volume Down | `volume decrease` |
|
|
| `XF86AudioMute` | Mute | `volume muteOutput` |
|
|
| `XF86AudioMicMute` | Mic Mute | `volume muteInput` |
|
|
| `XF86AudioPlay` | Play/Pause | `media playPause` |
|
|
| `XF86AudioNext` | Next Track | `media next` |
|
|
| `XF86AudioPrev` | Previous | `media previous` |
|
|
| `XF86MonBrightnessUp` | Brightness Up | `brightness increase` |
|
|
| `XF86MonBrightnessDown` | Brightness Down | `brightness decrease` |
|
|
|
|
### Wallpaper
|
|
|
|
The wallpaper layer is placed in the backdrop:
|
|
|
|
```kdl
|
|
// In ~/.config/niri/cfg/rules.kdl
|
|
layer-rule {
|
|
match namespace="^noctalia-wallpaper*"
|
|
place-within-backdrop true
|
|
}
|
|
```
|
|
|
|
The background color is set to transparent to allow the wallpaper to show:
|
|
|
|
```kdl
|
|
// In ~/.config/niri/cfg/layout.kdl
|
|
layout {
|
|
background-color "transparent"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `noctalia-qs` / `qs` | Quickshell runtime |
|
|
| `imagemagick` | Image processing |
|
|
| `brightnessctl` | Brightness control |
|
|
| `ffmpeg` | Media processing |
|
|
| `qt6-multimedia` | Qt multimedia |
|
|
| `python` | Python runtime |
|
|
| `wlr-randr` | Display information |
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [niri](niri/index.md) — Compositor configuration
|
|
- [[displays|displays]] — Display layout
|
|
- [[cachyos|cachyos]] — Operating system documentation
|