---
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