description: Umbriel scrolling compositor config — Noctalia-only session, niri layout and springs, Hyprland-style named scratchpads, outputs, and keybindings.
---
[Umbriel](https://docs.noctalia.dev/umbriel/) is a wlroots scrolling compositor from the Noctalia project. The config ports the [niri](/desktop/niri) layout, rules, springs, and binds, and adds the per-app scratch workspaces from [Hyprland](/desktop/hyprland) as Umbriel scratchpads. The session starts only `noctalia`: its launcher, clipboard history, polkit agent, notifications, and OSD replace vicinae, cliphist, and polkit-gnome.
Linux `desktop` and `laptop` roles only (`.chezmoiignore.tmpl`). `umbriel` and its portal backend `xdg-desktop-portal-umbriel` (screenshots and screen sharing for portal clients) come from the `[cachyos]` repo (`packages.arch.desktop.cachyos`); the AUR `umbriel` is a placeholder and `umbriel-git` conflicts with the repo build, so other Arch machines install them by hand.
Umbriel watches these files and applies a valid save immediately; `umbriel config validate` checks them without a session. Include paths resolve against the symlinks in `~/.config/umbriel`, not the chezmoi source. Defining `[keybinds]` replaces Umbriel's built-in binds, so `binds.toml` is the complete set.
### Theme [#theme]
`~/.config/umbriel/noctalia.toml` holds the colors. Noctalia's umbriel template writes it on every theme change and its post-hook keeps `"noctalia.toml"` last in `[include.optional]`; the file is not managed by chezmoi.
| Cursor | `capitaine-cursors-light` 24, hidden while typing, follows keyboard focus (so scratchpads open on the output focus moved to) | niri, Umbriel |
| Layout | gap 8, presets 0.333 / 0.5 / 0.667, new columns 1/3 on every output, focus never centers, a lone column centers | niri |
| Appearance | corner radius 10, no shadows, wallpaper-only blur on every window, tab bar hidden for one tab | niri |
| Activation | apps may focus and reveal their windows (`focus_on_activate`), e.g. Noctalia notification actions | niri `honor-xdg-activation-with-invalid-serial` |
Umbriel owns `XDG_CURRENT_DESKTOP`, so niri's override is not carried over. niri's `XDG_MENU_PREFIX`/`kbuildsycoca6` startup (Dolphin associations) and the `INIR_*` quickshell variables are dropped.
## Outputs
Matched by monitor identity (`umbriel outputs` → `Config name`). The external scales bring each display to about 110 logical pixels per inch (the ultrawide's native density), so windows keep their size across them; the Studio Display and ultrawide match Hyprland. The laptop panel runs at 1.5 (149 logical ppi), denser than the externals, because scale 2 left too little room. It sits at the origin and every external sits directly to its left at negative x, bottoms aligned. The externals are used one at a time and share that slot.
| Display | Physical | Scale | Logical | Position | Other |
The Studio Display's phantom 640x480 connector, which niri switched off as `DP-5`, needs no rule: Umbriel leaves connectors without a preferred mode or identity disabled.
## Scratchpads
Named scratchpads replace Hyprland's `special:*` workspaces and `omarchy-toggle-scratch`. A window rule sends each app into its scratchpad when it opens; toggling an empty scratchpad runs `spawn_when_empty`. Shown scratchpads are maximized over a desktop dimmed to 0.6, on the output under the pointer.
| media, volume, brightness keys | `noctalia msg …`, also on the lock screen |
### Apps
`umbriel-launch PATTERN COMMAND…` focuses the next window whose app id matches `PATTERN` (case-insensitive), cycling on repeated presses, and runs `COMMAND` through `umbriel msg spawn` when none is open. It skips scratchpad windows. The binds call it as `~/.local/bin/umbriel-launch` because the session `PATH` has no `~/.local/bin`.
| `Mod+1`…`Mod+9`, `Alt+Q W E R Y U I O` | workspace 1–9 / 1–8 |
| `Mod+Shift+1`…`9`, `Alt+Shift+Q`…`O` | move window to that workspace |
Workspaces are dynamic per output. Not carried over: niri's named `w`/`h`/`x` workspaces (`niri-dynamic-workspaces`), center-visible-columns, window-only screenshots, the vicinae window switcher (use the overview), the Linear and AI-cycle launchers whose keys now toggle scratchpads, and the Omarchy-only Hyprland binds (`omarchy-pip`, `omarchy-summon`, notification dismiss, strata in the terminal's cwd).
