Umbriel

Add the following settings to your Umbriel configuration file, usually located at ~/.config/umbriel/config.toml. Umbriel’s packaged examples/config.toml is a useful reference for the complete configuration. Umbriel also provides dedicated documentation for configuration, window rules, and layer rules.

Autostart Noctalia

Add noctalia to the autostart array under [general]. Preserve any commands that are already in the array:

[general]
autostart = ["noctalia"]

Umbriel runs these commands once after startup and does not run them again when its configuration is reloaded.

Compositor Settings

These settings provide rounded windows, consistent borders, and a blurred compositor background:

[appearance]
prefer_no_csd = true
border_width = 2
corner_radius = 10

[appearance.blur]
enabled = true
optimized = true
passes = 2
radius = 3
noise = 0.02
brightness = 0.9
contrast = 0.9
saturation = 1.1

Adjust these values to match your preferred appearance. The full list of options is available in Umbriel’s Appearance and Animation references.

Window Rules

Use a window_rule to configure Noctalia’s settings window as floating with a predictable size. Umbriel combines matching rules in file order, so add this to your existing rules or to a dedicated included file:

# Blur all windows
[[window_rule]]
blur = true
blur_optimized = true

# Float Noctalia's settings window
[[window_rule]]
match.app_id = "^dev.noctalia.Noctalia$"
default_floating = true
default_size = [1020, 900]

match.app_id is an ECMAScript regular expression. The ^ and $ anchors make this rule apply only to Noctalia’s settings window. See Umbriel’s Window Rules reference for placement, workspace, opacity, blur, and focus options.

Layer Rules and Blur

Noctalia publishes blur regions for its layer-shell surfaces when the compositor supports the ext-background-effects protocol. Enable blur for the bar, notifications, dock, panels, and OSD with the layer rule from Umbriel’s example configuration:

[[layer_rule]]
match.namespace = "^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$"
blur = true
blur_ignore_alpha = 0.6
blur_optimized = false

The namespace expression targets Noctalia’s standard surfaces without matching unrelated layer-shell clients. blur_ignore_alpha = 0.6 avoids blurring highly transparent parts of a surface. blur_optimized = false makes this rule use the regular blur path instead of the optimized mode configured globally under [appearance.blur].

Layer-surface blur is disabled by default in Umbriel. Inspect active namespaces with:

umbriel layers

For the complete set of layer-rule options, see Umbriel’s Layer Rules reference.

IPC Keybinds

Umbriel can launch Noctalia IPC commands directly from its [keybinds] table. Add these bindings to ~/.config/umbriel/config.toml:

[keybinds]
"Mod+Space" = "spawn:noctalia msg panel-toggle launcher"
"Mod+S" = "spawn:noctalia msg panel-toggle control-center"
"Mod+Comma" = "spawn:noctalia msg settings-toggle"
"Alt+Tab" = "spawn:noctalia msg window-switcher hold"
"Mod+Shift+A" = "spawn:noctalia msg screenshot-annotate"
"Mod+Ctrl+A" = "spawn:noctalia msg annotate"

"XF86AudioRaiseVolume" = "spawn:noctalia msg volume-up"
"XF86AudioLowerVolume" = "spawn:noctalia msg volume-down"
"XF86AudioMute" = "spawn:noctalia msg volume-mute"
"XF86MonBrightnessUp" = "spawn:noctalia msg brightness-up"
"XF86MonBrightnessDown" = "spawn:noctalia msg brightness-down"

Mod uses Umbriel’s configured modifier from general.mod_key and defaults to Super in a native session. See Keybinds for more Noctalia IPC examples and the complete action reference.

Window minimisation

Noctalia tracks Umbriel’s minimise state in the taskbar, dock, window switcher, and launcher window results. Clicking a focused single-window taskbar or dock icon minimises it when Umbriel marks it as eligible. Clicking a minimised window restores and focuses it; multi-window icons continue cycling.

Use an Umbriel build that includes both boolean fields minimized and minimizable in its window IPC snapshots. If those fields are missing or invalid, or the IPC connection is unavailable, minimise state and controls remain unavailable. Missing or invalid fields are reported in Noctalia’s logs; update Umbriel when using an older build.

Optional Type to Launch

Noctalia can open its launcher when you start typing in umbriel’s overview.

A launcher opened by typing closes automatically when you leave the overview. Launchers opened normally are unaffected.

[shell]
umbriel_overview_type_to_launch_enabled = true

You can also enable this from Settings → Umbriel → Overview.

Optional Close on Launch

Close the overview when opening an app from the launcher.

[shell]
umbriel_overview_close_on_launch_enabled = true

Only launching an application (a desktop entry or one of its desktop actions) closes the overview; other launcher results such as calculator or emoji do not. You can also enable this from Settings → Umbriel → Overview.

Audio-reactive Effects

Enable Settings → Umbriel → Audio → Provide Audio to Umbriel to let Umbriel’s audio-reactive effects respond to your audio. This is disabled by default. You can also enable it in Noctalia’s configuration:

[shell]
umbriel_audio_provider_enabled = true

Enable an audio-reactive effect in Umbriel to see a response. No Noctalia visualizer widget is required.