Settings Application

Aqueous Settings is available for Dank Material Shell and Noctalia v5. Both frontends use the shared aqueous-config helper and edit the same TOML files as the compositor. Source Arch packages install the DMS frontend.

Install or enable the plugin

Dank Material Shell

Enable Aqueous Settings in DMS Settings → Plugins, then add its widget to DankBar. Left-click opens the attached popout; right-click opens a separate settings window. Both share one draft model across all bar instances.

The enabled plugin can also open without a bar widget:

dms ipc call aqueousSettings open
dms ipc call aqueousSettings toggle
dms ipc call aqueousSettings close

The plugin targets DMS 1.7 or newer and requires aqueous-config 0.7.0 or newer, plus aqueousctl. Helper 0.7.1 adds capability discovery. Its executable path can be configured in the plugin settings.

For a development checkout, run ./dms-plugin/packaging/dev-install.sh from the Aqueous repository. Reload changed plugin code through DMS’s plugin UI or dms ipc call plugin-scan reload aqueousSettings.

Drafts survive closing the window or popout. Apply or discard them before disabling or reloading the plugin or restarting DMS, which clears in-memory drafts.

Noctalia

Noctalia package variants install the v5 plugin and the same helper. Fresh Noctalia profiles are seeded with the source, enabled plugin, and bar widget. Existing profiles receive a one-time registration attempt without overwriting their bars or re-enabling a plugin the user later disables.

To register a standalone installation manually:

noctalia msg plugins source add aqueous path /usr/share/aqueous/noctalia-plugins
noctalia msg plugins enable aqueous/settings

Then add Aqueous Settings from Noctalia’s bar widget picker. You can also open the panel directly:

noctalia msg panel-toggle aqueous/settings:panel

Available pages

Overview

The overview shows the resolved configuration paths, whether each file is writable, helper/schema information, and a live workspace layout selector. The selector queries aqueousctl for a chosen output and can change that output’s active workspace layout immediately without editing TOML.

Appearance

Typed controls cover:

Global blur quality, noise, contrast, brightness, and vibrancy.
Stable or focus-sensitive opacity.
Workspace transition enablement and rate.
Static struts and maximize/fullscreen compatibility behavior.
Installed font families and faces, point size, and adapter status/retry.
Opt-in cursor theme and size management, including live application.

The standalone aqueous-settings application also provides Appearance → System bell controls for visual feedback, a custom sound-file path, and bell volume. Changes are saved in [bell] in wm.toml and take effect on reload. See System bell for the four modes and sound setup.

Typography is stored in ~/.config/aqueous/appearance.toml and synchronized to the selected shell, GSettings, GTK 3, GTK 4, and qt5ct/qt6ct when those adapters are installed or configured. Each target reports available, active, and synced state. DMS applies family, weight, and scale, with partial coverage for exact face, slant, width, and separately scaled bars. Noctalia applies the family and reports partial coverage for an exact face.

Cursor management applies theme and size through aqueousctl, updates GTK and the systemd/D-Bus activation environment, and writes ~/.config/uwsm/env-aqueous.d/90-aqueous-cursor for future sessions. Existing applications may keep their own cursor surfaces until restarted. DMS-mode helper operations do not write or reload Noctalia settings.

Layouts

The layouts page exposes all ten layouts, global gaps/borders/master settings, four layout slots, scrolling and recursive-layout options, and the complete stacking policy. Legacy float, floating, and stack values are presented as one canonical Stacking choice.

Stacking controls include placement policy, cascade offset, fine/coarse move steps, resize step, snap gap and threshold, edge resistance, and top-edge maximize. The named snap-layout editor can create as many as eight layouts with sixteen zones apiece, choose the default, edit stable layout and zone IDs, names, padding, and normalized geometry, and apply half/third/quarter presets. It can migrate legacy zones a through d into a named layout and create custom bindings for a layout, zone, or layout cycle. The legacy A-D coordinate editor remains available for existing configurations.

Named zones are strictly stacking-only. Dragging a stacking-owned window to an output edge shows the active layout’s zones; releasing over the selected zone commits it. Keyboard zone actions follow the same ownership check, so they do nothing in tiled, scrolling, Game Mode, or composable layouts—even when the focused window is a persistent floating overlay.

If several legacy stacking option sections coexist, the panel warns rather than silently choosing one. An explicit normalization operation merges known and unknown entries into [layout.options.stacking] and removes the aliases. Ordinary typed edits continue to update the effective existing alias in place.

Input

Typed controls cover focus-follows-pointer, mouse-follows-focus, focus-new-windows, freeform raising and delay, XKB layout/variant/options, keyboard repeat, legacy global pointer speed, and mouse/touchpad libinput settings.

Displays

The display canvas combines configured [[output]] entries with connected outputs. Monitor cards use a common scale, reflect their relative logical resolution, and remain visible when configured but offline. Drag a card before, after, above, or below another display; select normal or flipped rotation; or enter exact logical X/Y coordinates.

Dragging creates a draft only. Apply writes position/transform overrides to the matching outputs.toml entry. Other display settings continue to inherit from wm.toml until explicitly changed. General display-policy fields include startup/reload application and fallback profile.

Resolution and refresh selectors use advertised modes, including fractional refresh rates. Automatic refresh writes WIDTHxHEIGHT; an explicit rate writes WIDTHxHEIGHT@Hz. Offline outputs accept custom modes, and mode drafts survive movement and rotation. The canvas reflects resolution at the effective scale.

Choose Extended desktop or Mirror of … for a destination display. Mirrors remain selectable but are omitted from the arrangement canvas. Select compatible SDR, orientation, and refresh settings before applying mirroring; see Screen mirroring.

Rules

The ordered window-rule editor can add, duplicate, move, update, and delete rules. It covers identity and content-type matchers, layout/output/workspace, floating/state policy, stack layer, focus/task-list hints, placement and size, opacity/blur, client-buffer scaling, HDR expansion, and overlay preference. The scrolling full-width preset is also available.

Choose Unset for a rule’s layout to remove the layout field and preserve the workspace layout. Select game-mode explicitly when the rule should establish a Game Mode anchor. This applies to both settings editors.

When content type is the only matcher, the editor disables placement fields to make the compositor’s safety rule obvious. Aqueous treats every rule containing content_type as visual-only, so placement values combined with it are ignored. Rules require at least one matcher, and typed values are validated before writing. Game Mode companion and fallback layout settings are available on the same page.

Keybinds

Every built-in action is listed, including currently unbound stacking actions. A field accepts one chord or comma-separated chords. Custom entries expose both chord and verb and can be created or deleted. Snap-layout shortcuts produce the correct builtin:snap_zone:<layout>/<zone>, builtin:set_snap_layout:<layout>, or builtin:cycle_snap_layout form and fall back to the legacy builtin:snap_zone:a preset when no named layout exists. The page also edits launcher, terminal, screenshot, and lock commands.

Advanced

The raw editors expose the complete effective wm.toml, outputs.toml, layout.toml, input.toml, rules.toml, and plugin-owned appearance.toml. Use this page for composable regions, output profiles, gestures, managed commands, workspace mappings, layer rules, or any newer option not yet given a typed control.

Search filters schema-backed settings on the selected page in DMS. Reset arrows stage defaults, and numeric controls report input errors. Resolve raw and typed drafts affecting the same file before Validate or Apply. Apply or discard a rule reorder before making other rule edits.

Safe editing model

The helper resolves the same environment, XDG, and sidecar paths as Aqueous. A system file under /etc/xdg is shown as inherited; Apply creates a user override instead of modifying it.
Edits remain drafts until Apply. Validate performs the same schema and structural checks without writing.
Each request carries the generation that was loaded. If another program changes a file, stale Apply is rejected and your draft remains available.
Existing comments, ordering, whitespace, and unknown keys survive typed changes. Raw files receive structural validation and the compositor’s 1 MiB size limit.
Multi-file changes are copied to the plugin’s persistent backup directory, then written with atomic replacement. Aqueous’s normal hot reload applies the result; the plugin never restarts the compositor.

DMS backups live under ${XDG_STATE_HOME:-$HOME/.local/state}/aqueous/dms-plugin/backups. If Apply times out or returns an invalid response, reload and inspect the saved state before retrying; the write may already have completed.