Configuration

Aqueous uses five focused TOML files. Only wm.toml is required; the other files are sidecars for keeping each policy area understandable.

• Directory~/.config/aqueous/

  • wm.toml keybindings, commands, struts, global effects, system bell, and state policy
  • outputs.toml physical outputs, HDR, positions, and profiles
  • layout.toml layouts, options, slots, named stacking snap layouts, and mappings
  • input.toml keyboard, focus, gestures, mouse, touchpad, and tablet policy
  • rules.toml ordered window/layer rules and Game Mode policy
  • appearance.toml helper-managed font and cursor preferences, not read by the compositor
  • session.toml desktop shell selection, not read as compositor policy

The paths below describe stable Aqueous. Co-installable Git packages use ~/.config/aqueous-git/ and suffixed tools. See instance paths.

Parsing and reloads

Aqueous accepts a deliberately small TOML-compatible subset: sections, repeated tables, key/value assignments, binding and position arrays, inline maps for environment variables, and # comments. Unknown keys and malformed values are generally ignored individually while valid recognized values elsewhere still apply. Tablet rules are validated as a collection: unknown tablet keys, duplicate IDs/keys, invalid selectors or more than 32 merged rules are errors. An invalid tablet reload retains the previous tablet policy; at startup it leaves unconfigured behavior in place. See Tablets.

The compositor fingerprints the resolved files once per second. Changed files are parsed into complete replacement snapshots and applied in one manage cycle, so a cycle never sees half of an update. This includes keybindings, layouts, rules, input, effects, and output policy. reload_config performs the same reload immediately; reload_rules refreshes only rules.toml. From a terminal, aqueousctl session reload --json requests the full reload. Startup-only render settings still require a session restart.

[keybinds]
reload_config = "Super+R"
reload_rules = "Super+Shift+R"

A rule parse failure preserves the previous valid rule snapshot. A missing optional rule file disables rules; other missing sidecars leave the values from wm.toml or compiled defaults in place.

File discovery

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
outputs.toml	$AQUEOUS_OUTPUTS, $XDG_CONFIG_HOME/aqueous/outputs.toml, ~/.config/aqueous/outputs.toml, /etc/xdg/aqueous/outputs.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 beside wm.toml; use an absolute or ~-prefixed input or rules path. The system bell’s sound_file is an exception: it accepts an absolute path or one relative to the loaded wm.toml, with no ~ or variable expansion. See System bell.

layout.toml keeps compatibility-first discovery

An existing ~/.config/aqueous/layout.toml wins before $AQUEOUS_LAYOUT and [layout].path. Rename that file before selecting an alternate location.

How files combine

layout.toml and input.toml overlay matching values from wm.toml one recognized key at a time. Omitted values continue to inherit. Define a mapping or device policy in one place when possible so precedence remains obvious.

Tablet rules use complete replacement instead: each [[input.tablet]] entry in input.toml replaces the inherited entry with the same id and appends in sidecar order. The last matching rule wins. Removing a sidecar rule restores any inherited rule on reload. A valid remap during pen proximity waits until the pen leaves detection range.

Physical display values in outputs.toml are preferred. Once that file contains declarative display policy, matching wm.toml output entries form the base and outputs.toml supplies later overrides. Omitted fields still inherit; a file containing profiles only does not silently opt an existing setup into the new precedence.

Layout resolution uses this order:

1. A live layout selected for the output/workspace.
2. An output-scoped [[workspace]] mapping.
3. A workspace-only mapping.
4. The matching output’s default layout.
5. [layout].default.

Minimal configuration

~/.config/aqueous/wm.toml

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

[actions]
toggle_start_menu = "dms ipc call spotlight toggle"
spawn_terminal = "ghostty"
screenshot = "dms screenshot region"

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

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

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

~/.config/aqueous/outputs.toml

[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

[[output]]
name = "DP-1"
enabled = true
mode = "2560x1440@144"
scale = 1.0
position = [1536, 0]
adaptive_sync = true

Output positions are logical coordinates after scaling. Unconfigured outputs receive non-overlapping horizontal positions. Live layer-shell exclusive zones are applied before [struts]; keep static struts at zero when a bar already reserves its own space.

Managed commands

Repeated [[exec]] blocks start or supervise processes. 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 is eligible at compositor startup.
• reload runs after a full configuration reload.
• always is eligible in both cases.
• once avoids duplicate children with the same name.
• restart retries a child after a nonzero exit until it succeeds.

The package’s desktop shell is already managed as a graphical-session service and does not need a duplicate [[exec]] entry.

Application launch profiles

Repeated [[application]] blocks provide a shell-free path for applications that need toolkit-specific Wayland or decoration options:

[[application]]
name = "vesktop-ssd"
desktop_id = "vesktop.desktop"
command = "/usr/bin/vesktop"
args = ["--enable-features=WaylandWindowDecorations"]
env = { ELECTRON_OZONE_PLATFORM_HINT = "auto" }

[keybinds.custom]
"Super+Shift+V" = "launch:vesktop-ssd"

name and command are required, and command must be an absolute executable path. A profile supports up to 16 arguments and 16 environment overrides. desktop_id is optional descriptive metadata. It does not change the system launcher or cause Aqueous to rewrite installed desktop entries.

Unlike spawn:, launch: does not invoke /bin/sh. It passes every args element as a separate argument, inherits the compositor environment, replaces the named env entries, and executes the application directly. Shell expansion, pipelines, substitutions, and ~ expansion therefore do not apply. Use spawn: or [[exec]] when a command intentionally needs shell syntax.

State and client scaling

[state]
maximize_full_output = false
# fullscreen_hides_bar is accepted for compatibility; layer hiding is not implemented.

[scaling]
buffer_policy = "native" # native | integer-ceil

maximize_full_output = false keeps maximized windows in the usable area. integer-ceil asks compatible clients for a larger integer-scale backing buffer while retaining fractional logical geometry. Prefer a per-window rule when testing this higher-cost compatibility mode.

System bell

The [bell] section in wm.toml controls visual feedback, custom sounds, and bell volume. Visual feedback is the default; choose "both" to add a sound:

[bell]
mode = "both" # visual | sound | both | off
sound_file = "sounds/bell.wav"
volume = 0.5

Bell settings reload with the rest of the configuration. Changing them cancels active feedback. See System bell for defaults, sound requirements, path handling, and feedback behavior.

Edit with the settings application

Pearl uses the canonical aqueous-config backend for compositor configuration. The helper validates candidates, preserves comments and unrelated keys, detects external edits, and reports save/reload outcomes. Protected display changes use a preview and confirmation before persistence. The old DMS/Noctalia settings plugin instructions no longer apply to current packages. See Settings and configuration helper.

wm.toml reference

outputs.toml reference

layout.toml reference

input.toml reference

Tablet setup

System bell

rules.toml reference

Command-line tools