Configuration

Aqueous keeps its configuration in four small TOML files. wm.toml is the entry point; the other files are optional overlays that keep layout, input, and window policy easy to navigate.

• Directory~/.config/aqueous/

  • wm.toml outputs, keybindings, commands, struts, and global policy
  • layout.toml layout engines, slots, and workspace/output defaults
  • input.toml keyboard, mouse, touchpad, and trackpoint policy
  • rules.toml per-window behavior and game-mode policy

How parsing and reloads work

Aqueous accepts a deliberately small TOML-compatible subset: sections, repeated tables, key/value assignments, arrays used by bindings and positions, inline maps used by exec.env, and # comments. Unknown keys and malformed values are ignored individually, while valid recognized values elsewhere in the file still apply.

The compositor checks the resolved files once per second. A changed file is loaded into a complete replacement snapshot and then applied in one manage cycle. This includes keybindings, input settings, layouts, rules, effects, and output configuration. Press Super+R to run the same reload immediately.

[keybinds]
reload_config = "Super+R"
# reload_rules = "Super+Shift+R" # optional: reload only rules.toml

Tip

Keep each setting in one file. Sidecars merge over wm.toml, but avoiding duplicate declarations makes precedence obvious when you return to the configuration later.

File discovery

For the standard setup, put all four files in ~/.config/aqueous/. Advanced setups can select alternate paths with environment variables or sidecar selectors:

File	Search order (first match wins)
wm.toml	$AQUEOUS_CONFIG, $XDG_CONFIG_HOME/aqueous/wm.toml, ~/.config/aqueous/wm.toml, /etc/xdg/aqueous/wm.toml
layout.toml	existing ~/.config/aqueous/layout.toml, $AQUEOUS_LAYOUT, [layout].path, $XDG_CONFIG_HOME/aqueous/layout.toml, /etc/xdg/aqueous/layout.toml
input.toml	$AQUEOUS_INPUT, [input].path, $XDG_CONFIG_HOME/aqueous/input.toml, ~/.config/aqueous/input.toml, /etc/xdg/aqueous/input.toml
rules.toml	$AQUEOUS_RULES, [rules].path, $XDG_CONFIG_HOME/aqueous/rules.toml, ~/.config/aqueous/rules.toml

~ is expanded in explicit paths. A relative [layout].path is resolved next to wm.toml; use an absolute or ~-prefixed path for [input].path and [rules].path.

layout.toml has compatibility-first discovery

An existing ~/.config/aqueous/layout.toml takes precedence over $AQUEOUS_LAYOUT and [layout].path. Remove or rename that file before using an alternate layout path.

A practical wm.toml

This example is intentionally compact. It configures two outputs, reserves no extra panel space, defines the commands used by built-in bindings, and points to the three sidecars.

[display]
apply_on_start = true
apply_on_reload = true

[[output]]
name = "eDP-1"
enabled = true
mode = "1920x1200@60"
scale = 1.25
position = [0, 0]
primary = true
layout = "scrolling"

[[output]]
name = "DP-1"
enabled = true
mode = "2560x1440@144"
scale = 1.0
position = [1536, 0] # logical coordinates after eDP-1's scale
adaptive_sync = true
# Enable only on capable DRM outputs; uses the fixed HDR10 profile.
hdr = true
layout = "tile"

[struts]
top = 0
bottom = 0
left = 0
right = 0

[actions]
toggle_start_menu = "noctalia msg panel-toggle launcher"
spawn_terminal = "foot"
lock_screen = "swaylock -f"

[layout]
path = "~/.config/aqueous/layout.toml"
force_ssd = false

[input]
path = "~/.config/aqueous/input.toml"

[rules]
path = "~/.config/aqueous/rules.toml"

Output positions use logical coordinates. If you omit position, Aqueous places otherwise unconfigured outputs in a non-overlapping horizontal row. Display fields accept connector-name globs such as DP-*; layout-only output matching uses an exact connector name. An edid selector is also accepted when connector names are not stable. Run aqueousctl outputs to see connector names, supported modes, and the current/preferred mode before writing a display block.

Layer-shell panels usually reserve their own space

[struts] adds fixed margins after layer-shell exclusive zones are applied. Leave these values at zero when your bar already declares an exclusive zone; otherwise you will reserve the panel area twice.

Display transforms and profiles

transform accepts normal, 90, 180, 270, and the four flipped-* variants. scale must be between 0.5 and 3.0. Set hdr = true only for a capable DRM output; Aqueous uses a fixed HDR10 profile (10-bit BT.2020 with PQ).

Named profiles use the same display fields as [[output]] and can be selected through Aqueous’s output-service API. A fallback profile can provide a safe configuration when a normal output transaction is rejected.

[display]
fallback_profile = "internal-only"

[[display.profile]]
name = "internal-only"

[[display.profile.output]]
name = "eDP-1"
enabled = true
position = [0, 0]
primary = true

[[display.profile.output]]
name = "DP-*"
enabled = false

Managed commands

Use repeated [[exec]] blocks for processes Aqueous should start or supervise. Both name and command are required.

[[exec]]
name = "wallpaper"
command = "swaybg -i ~/.config/aqueous/wallpaper.png -m fill"
when = "startup" # startup | reload | always
once = true
restart = false
log = "/tmp/aqueous-wallpaper.log"
env = { XDG_CURRENT_DESKTOP = "Aqueous" }

• startup runs during compositor startup.
• reload runs after a configuration reload.
• always is eligible in both cases.
• once = true prevents the same named command from being started twice.
• restart = true retries a child that exits unsuccessfully.

The packaged Noctalia shell is managed by a systemd user service, so it does not need a second [[exec]] entry.

Window-state behavior

[state]
fullscreen_hides_bar = true
maximize_full_output = false

maximize_full_output = false keeps maximized windows inside the output’s usable area. The fullscreen_hides_bar compatibility key is parsed, but hiding upper layer-shell surfaces is not currently implemented.

wm.toml Reference

Keybindings

Layouts

Input

Window Rules

Visual Effects