Umbriel
Haxorus uses Umbriel as its Wayland compositor. It owns outputs, workspaces, window placement, input, and compositor effects. Noctalia provides the shell and desktop services.
Choose Umbriel in GDM to start the session. X11 applications run through
xwayland-satellite. Screen sharing and portal screenshots use
xdg-desktop-portal-umbriel.
Configuration
conf/modules/de/umb.nix enables the Umbriel NixOS module and configures
programs.umbriel.settings through Home Manager. The ThinkPad configuration
imports umb.nix.
Home Manager generates ~/.config/umbriel/config.toml from the Nix attribute
set. Umbriel does not write overrides or modify that file. Change umb.nix and
rebuild instead of editing the Home Manager symlink. Umbriel watches the file
and applies valid updates without a restart; it keeps the last working config
if a reload fails.
The repository sets the session environment, laptop output, workspace model,
layout, colors, appearance, input, keybindings, window rules, and animations.
An autostart command publishes the Wayland environment and retries
umbriel-session.target until systemd accepts it. This prevents a user-manager
startup race from leaving the session without Noctalia. Unspecified settings
retain Umbriel’s defaults. See the upstream
configuration reference
when adding an option.
Window-management model
Every workspace uses Dwindle. There are no Master, Scrolling, or per-workspace
layout overrides. New windows split the focused tile along its longer edge and
open in the right or bottom half. preserve_split = true keeps that split
direction when surrounding geometry changes.
Tiled windows have 4 px gaps. Windows use 8 px corners and a 1 px border, with
no outer border, blur, or shadow. Unfocused windows use 97% opacity. Colors come
from desktop-theme.nix.
Super-Shift-F toggles the focused window between tiled and floating, then
centers it. Other floating windows retain their own size and position unless a
window rule supplies defaults. Super plus left or right mouse drag moves or
resizes a window.
Workspaces
The laptop output has ten static, numbered positions. Empty workspaces remain
available. Super-1 through Super-0 select positions 1 through 10 on the
output under the pointer. Re-selecting the active workspace returns to the
previous workspace on that output.
Workspaces belong to outputs rather than forming one global list. An unconfigured external output uses Umbriel’s default dynamic workspace model. It starts with one workspace, adds an empty workspace after the last occupied one, and removes other empty inactive workspaces.
No workspace currently overrides the global Dwindle layout. Add a workspace
rule in umb.nix if a workspace needs Master or Scrolling.
When an output disconnects, Umbriel moves its windows to another enabled output. If the output reconnects, its workspaces, windows, active workspace, and layout state return to it.
Outputs
The ThinkPad panel is eDP-1. It starts at [0, 0], uses scale 1.2, and
arranges its workspaces horizontally. Its mode is not fixed, so Umbriel uses
the display’s preferred mode.
List connected outputs and their copyable configuration names from an Umbriel session:
umbriel outputs
umbriel outputs --json
Add or change an output.<name> entry in umb.nix to set a monitor’s mode,
scale, position, workspace inventory, or workspace axis. Prefer the reported
monitor name for rules tied to one physical display. Prefer a connector such as
DP-1 for rules tied to one port.
Outputs without an explicit position are placed automatically from left to right. Docking and undocking therefore does not require a fixed arrangement. Disconnected windows return to their original output when it reconnects.
Scratchpad
There are no named scratchpads. Umbriel therefore provides its implicit global
default scratchpad:
Super-Shift-Sstores the focused window.Super-Sshows or hides all stored windows on the pointer output.umbriel msg window-restore-from-scratchpadrestores the focused stored window to its saved output and workspace.
There is no restore keybinding. Showing a scratchpad does not remove its windows from it. Scratchpad windows float, and the visible scratchpad dims the output by 30%. The scratchpad can roam between outputs and returns with an output after a disconnect and reconnect.
Keybindings
Mod is fixed to Super, including nested sessions. Bindings dispatch
Umbriel actions or spawn commands.
The same action strings can be run with umbriel msg <action>.
Applications
| Key | Action |
|---|---|
Super-Return | Open Ghostty. |
Super-Z | Open Ghostty running Zellij. |
Super-B | Open Zen Browser. |
Super-E | Open Nautilus. |
Windows
| Key | Action |
|---|---|
Super-Q | Close the focused window. |
Super-Shift-F | Toggle floating and center the window. |
Super-Shift-G | Toggle fullscreen. |
Super-Shift-H | Toggle maximize. |
Super-Shift-P | Toggle pinned state. |
Super-Ctrl-H/L | Decrease or increase width by 10%. |
Super-Ctrl-K/J | Decrease or increase height by 10%. |
Super-Alt-H/L | Move the Dwindle column left or right. |
Super-Alt-K/J | Move the window up or down. |
Super-Mouse left drag | Move a tiled or floating window. |
Super-Mouse right drag | Resize a tiled or floating window. |
Focus
| Key | Action |
|---|---|
Super-H, Super-Left | Focus left. |
Super-J, Super-Down | Focus down. |
Super-K, Super-Up | Focus up. |
Super-L, Super-Right | Focus right. |
Focus follows the pointer. Moving the pointer does not warp it to the focused window, and typing does not hide it.
Workspaces
| Key | Action |
|---|---|
Super-1..0 | Switch to workspace 1 through 10. |
Super-Shift-1..0 | Move the focused window to workspace 1–10. |
Super-Wheel up | Switch to the previous workspace. |
Super-Wheel down | Switch to the next workspace. |
Wheel switching has a 150 ms cooldown. Three-finger horizontal touchpad swipes also switch workspaces.
Scratchpad
| Key | Action |
|---|---|
Super-S | Show or hide the default scratchpad. |
Super-Shift-S | Move the focused window to the scratchpad. |
Noctalia
| Key | Action |
|---|---|
Super-R, Super-Space, Super-P | Toggle the launcher. |
Super-V | Toggle clipboard history. |
Super-Shift-V | Clear clipboard history. |
Super-N | Invoke the latest notification. |
Super-Shift-N | Toggle Do Not Disturb. |
Media
| Key | Action |
|---|---|
Volume up/down | Change output volume. |
Volume mute | Toggle output mute. |
Microphone mute | Toggle microphone mute. |
Brightness up/down | Change display brightness 5%. |
Media next/previous | Change tracks. |
Media play/pause | Toggle playback. |
These hardware-key bindings work while the session is locked.
Screenshots
| Key | Action |
|---|---|
Print | Capture a region with Noctalia. |
Shift-Print | Capture the focused output with Noctalia. |
Screenshot bindings do not repeat.
Session
| Key | Action |
|---|---|
Super-Shift-L | Lock through Noctalia. |
Super-Escape | Toggle Noctalia’s session panel. |
Super-Shift-/ | Toggle Umbriel’s keybinding cheatsheet. |
Super-Shift-R | Reload the Umbriel configuration. |
Power controls are available from the Noctalia session panel.
Window rules
The rules in umb.nix provide these exceptions:
- Unfocused windows use 97% opacity.
- Noctalia Settings opens floating at 1020×900.
- Umbriel’s share picker opens floating at 800×600.
- Calculator, Nautilus, PulseAudio controls, NetworkManager’s connection editor, GNOME Settings, and desktop portal windows open floating.
- Browser picture-in-picture windows open floating, 20 px from the bottom-right corner.
Use umbriel windows to inspect the app ID and title before adding a rule. Keep
rules for application behavior in umb.nix rather than relying on a window’s
current title or position by hand.
Debugging
Validate the generated config and inspect compositor state:
umbriel validate
umbriel outputs
umbriel workspaces
umbriel windows
umbriel layers
Inspect the session services and logs when startup or integration fails:
systemctl --user status umbriel.service noctalia.service
journalctl --user -b -u umbriel.service -u noctalia.service
journalctl --user -b -u xdg-desktop-portal-umbriel
Umbriel can run nested in GNOME for basic compositor testing, but output,
session lock, input gesture, and portal behavior must be tested in a real
Umbriel session. Run umbriel validate after input updates, then test
lock/unlock, suspend, screenshots, external outputs, and screen sharing.