Configuration

Starting configuration

The packaged starting configuration is examples/config.toml. Copy it before making local changes:

mkdir -p ~/.config/umbriel
cp /usr/share/umbriel/config.toml ~/.config/umbriel/config.toml

A manual installation under /usr/local places it at /usr/local/share/umbriel/config.toml. Nix users should prefer programs.umbriel.settings in Home Manager or hjem.

Umbriel watches the active configuration and applies valid changes when you save. Most options reload immediately; reference tables identify options that require a restart. If a reload fails, Umbriel keeps the last working configuration and tries again on the next save.

Without -c, Umbriel checks these locations in order:

1. $XDG_CONFIG_HOME/umbriel/config.toml
2. Each $XDG_CONFIG_DIRS/umbriel/config.toml
3. The packaged share/umbriel/config.toml

Use umbriel -c <path> to select one exact file. Umbriel never creates or modifies a user configuration automatically.

Diagnostics

Configuration warnings and errors appear in a panel on the primary output. Errors keep the previous working configuration active. A warning-only panel closes after ten seconds; an error remains until the next successful reload.

Check a file without starting the compositor:

umbriel config validate

The command prints every diagnostic with its file, line, and column, and exits nonzero when it finds a problem.

List every configuration key the installed binary accepts:

umbriel config schema
umbriel config schema --json

Without --json it prints how many options each section has. With --json it prints each key’s path, type, range, accepted values, format, and built-in default, plus the binary’s version and revision (null for a build outside git). name[] marks the entries of an array of tables, such as window_rule[].match.app_id, and <name> a name you choose, such as output.<name>.scale.

Include

Split a configuration into smaller files with required or optional includes:

[include]
files = [
  "appearance.toml",
  "keybinds.toml",
]

[include.optional]
files = [
  "~/.config/umbriel/noctalia.toml",
]

Paths are relative to the file containing the include. ~, $VAR, and ${VAR} are expanded. Missing optional files are ignored and watched, so creating one later reloads the configuration.

Included files are applied in list order. The including file is applied last:

• Tables merge by key.
• Rule lists such as [[window_rule]] and [[workspace]] collect entries.
• Plain arrays and scalar values are replaced by the last file that sets them.
• Setting a rule list to [] discards entries collected earlier.

Every file must contain valid TOML. Duplicate device or workspace selectors, and an effect preset defined in two files, are errors even when they come from different files: at startup Umbriel uses the default configuration and shows an error banner (unless the configuration sets [drm], which refuses to start), and a reload keeps the previous configuration.

If any included file defines [drm], also declare [drm] in the main file. This prevents an incomplete GPU exclusion policy from loading when an include is unavailable.

General

[general]
autostart = ["noctalia", "kitty"]
mod_key = "Super"
xwayland = true
xwayland_native_resolution = false
show_cheatsheet = true
focus_on_activate = false
honor_restored_maximize = false

Key	Type	Default	Description
autostart	string array	[]	Commands started once with the session. Changes require a restart.
mod_key	string	Super, or Alt when nested	Modifier represented by Mod in keybinds.
xwayland	bool	true	Start Xwayland lazily for X11 applications. Changes require a restart.
xwayland_native_resolution	bool	false	Show outputs to X11 applications at their physical resolution, so they render sharp on scaled outputs. Changes require a restart.
show_cheatsheet	bool	true	Show the keybind cheatsheet when Umbriel starts.
focus_on_activate	bool	false	Let application activation requests focus and reveal their target.
honor_restored_maximize	bool	false	Honor maximize requests an application makes while its window opens, until it acknowledges its opening layout.

Xwayland must be installed and available on PATH when X11 support is enabled. It starts when the first X11 application connects.

X11 applications have no per-output scale. By default they see every output at its logical size, and Umbriel upscales their windows on outputs with a scale above 1, which looks soft. With xwayland_native_resolution = true they see each output at its physical size instead: a 3840x2160 output at scale 1.25 appears to them as 3840x2160 rather than 3072x1728. Their windows render at one pixel per screen pixel and stay sharp, but X11 applications that do not scale their own interface look smaller on scaled outputs. Games benefit most.

DRM devices

Use [drm] only when Umbriel should leave a GPU unopened in a native session. Omit the section for automatic GPU discovery. Changes require a restart.

[drm]
ignored_pci_addresses = ["0000:01:00.0"]
# ignored_devices = ["/dev/dri/by-path/pci-0000:01:00.0-card"]

Key	Type	Default	Description
ignored_devices	string array	[]	Absolute card or render-node paths. Prefer stable /dev/dri/by-path links.
ignored_pci_addresses	string array	[]	PCI addresses in domain:bus:slot.function form.

Umbriel does not bind or unbind PCI drivers. Configure that lifecycle in libvirt or equivalent host tooling.

Limits

• GPU exclusions affect native sessions only.
• Startup fails when no allowed GPU can initialize.
• Secondary GPUs must support the primary GPU’s DMA-BUF formats and modifiers.
• Software rendering is incompatible with GPU exclusions.
• With exclusions, WLR_BACKENDS supports only drm and optional libinput.

Environment

[environment]
ELECTRON_OZONE_PLATFORM_HINT = "auto"
SDL_VIDEODRIVER = "wayland"

These variables apply to Umbriel and commands started in its session. In a managed native session, they are also published to the systemd user manager for session services such as Noctalia. Nested sessions do not modify the host session environment.

Names must match [A-Za-z_][A-Za-z0-9_]*, and values must be strings. Umbriel owns its display and session variables, so this section cannot override WAYLAND_DISPLAY, WAYLAND_SOCKET, DISPLAY, UMBRIEL_SOCKET, XDG_CURRENT_DESKTOP, XDG_SESSION_DESKTOP, or XDG_SESSION_TYPE.

Environment changes require an Umbriel restart. Fully quit and relaunch long-running applications that survived the restart.

Removing a key does not clear a value already published to the systemd user manager. Run systemctl --user unset-environment NAME to remove it immediately, or wait for the user manager to exit.

Events

Run commands when the laptop lid closes or opens:

[events]
lid_close = "notify-send 'The laptop lid is closed!'"
lid_open = "notify-send 'The laptop lid is open!'"

Umbriel runs the command for the current lid state once during startup, after the compositor IPC socket is ready, then runs commands when that state changes. This also handles signing in while the lid is already closed or already open. If the system reports more than one lid switch, the combined state remains closed while any switch is closed. Device removal and re-addition during suspend do not repeat a command unless the combined state actually changed.

Logical output actions can remove the laptop panel from the desktop instead of merely powering it off:

[events]
lid_close = "umbriel msg output-disable:eDP-1"
lid_open = "umbriel msg output-enable:eDP-1"

Screencast

Target-changing screencast actions ask for confirmation the first time they are used during an active single-source share. Dismissing the panel cancels only the pending action, so invoking one again asks again. Approval lasts until the share ends.

[screencast]
disable_dynamic_confirmation = false

Key	Type	Default	Description
disable_dynamic_confirmation	bool	false	Apply set and follow actions immediately without first confirming them. This can expose another window or output after an accidental key press.

Scratchpads

With no [[scratchpad]] entries, Umbriel provides one implicit scratchpad named default:

[keybinds]
"Mod+Shift+Space" = "window-move-to-scratchpad"
"Mod+Space" = "scratchpad-toggle"

To configure several scratchpads, give each one a unique name and include that name in its actions:

[[scratchpad]]
name = "terminal"

[[scratchpad]]
name = "music"

[keybinds]
"Mod+Space" = "scratchpad-toggle:terminal"
"Mod+M" = "scratchpad-toggle:music"

Defining a named scratchpad removes the implicit default. See Scratchpads for window assignment and behavior.

Idle inhibition

Umbriel honors idle inhibitors only while their application surface is mapped and visible. Switching away from its workspace, hiding it in a scratchpad, disabling its output, or locking the session suspends the inhibitor until the surface becomes visible again.