Aqueous

Aqueous is a Wayland compositor and window manager written in Zig. Layouts, rules, keybindings, input policy, workspaces, display management, motion, and visual effects run together in one native process. It began as a fork of River, but its current window-management policy and TOML configuration are Aqueous-owned and integrated directly into the compositor.

What Aqueous can do

Switch between ten native layouts on each output and workspace: tile, monocle, grid, rows, dwindle, reverse-dwindle, scrolling, stacking, game-mode, and composable.
Use stacking as a complete freeform desktop with persistent geometry and z-order, MRU focus, focus raising, placement policies, edge resistance, keyboard movement and resizing, half/quarter snapping, and up to eight named snap layouts with sixteen zones each. Edge previews and named-zone actions are deliberately stacking-only. The legacy names float, floating, and stack remain accepted.
Divide a workspace into as many as four normalized composable regions, each running an independent leaf layout with its own ordering and state.
Arrange PaperWM-style scrolling columns, including vertical stacks, viewport navigation, column consume/expel actions, pointer rearrangement, and portrait-aware placement.
Apply first-match window and layer-shell rules for identity, content type, output, workspace, layout, floating geometry, placement, stack layer, focus, task switcher visibility, fullscreen, scaling, opacity, blur, HDR expansion, and DRM overlay preference.
Configure modes, scale, transforms, logical positions, adaptive sync, HDR, Auto HDR, primary-output fallback, hotplug behavior, and named output profiles through atomic compositor transactions.
Mirror an SDR display to a projector or capture card on the same device, with independent refresh rates and aspect-ratio-preserving letterboxing.
Configure XKB, repeat, focus policy, mice, touchpads, pointer constraints, gestures, tablets, and input-method/text-input clients.
Use compositor-side rounded corners, damage-aware backdrop blur, focus-sensitive opacity, animated window placement, sliding workspace transitions, and a workspace-local window overview.
Run native Wayland and optional embedded XWayland applications without an external XWayland bridge or policy client.
Integrate shells through typed window, workspace, keyboard, overview, and session commands, with persistent socket IPC for state subscriptions.

These guides track the source tree as of September 8, 2026. Distribution packages may lag behind; use aqueous -version and aqueousctl shell capabilities --json to check your installed build.

Layouts and interaction

Aqueous resolves final placements from stable window handles, then applies the result as one manage cycle. Fullscreen, maximized, minimized, floating, transient, and rule-owned state are handled consistently around that result.

Pointer actions follow the active layout. Super+left-drag rearranges tiled windows; Super+right-drag resizes tiles or scrolling members and manipulates freeform windows. Client-side title-bar move/resize, maximize, minimize, and fullscreen requests are integrated for both XDG and XWayland windows when the request is valid. Floating windows can cross differently scaled or transformed outputs while remaining reachable.

The Super+W overview displays frozen thumbnails of every focusable window on the active workspace, including scrolling windows outside the viewport. It is keyboard navigable and does not reconfigure clients while open.

Visuals, color, and capture

The default build uses Aqueous’s Vulkan effects backend for rounded corners and backdrop blur. Opacity can be global, focus-sensitive, or selected by a rule. Animations and Vulkan effects can also be excluded at build time.

Capable DRM outputs can use a 10-bit BT.2020/PQ HDR10 profile with selectable peak mastering level and SDR white level. Aqueous exposes Windows scRGB and BT.2100 color descriptions for Wine/Proton and can optionally expand eligible SDR highlights toward the HDR peak. Rule-selected direct overlay promotion is available as an opt-in, with automatic fallback to composition.

Screen capture, task switchers, panels, launchers, portals, session lockers, clipboard managers, virtual input tools, and color-aware applications are served through standard Wayland, ext, and wlroots protocols.

Configuration and desktop tools

Aqueous discovers five compatible TOML files under ~/.config/aqueous/:

wm.toml — keybindings, commands, struts, global effects, and policy.
outputs.toml — preferred physical output policy and profiles.
layout.toml — layout defaults, options, slots, snap zones, and mappings.
input.toml — XKB, keyboard, focus, gesture, and libinput policy.
rules.toml — window/layer rules and Game Mode policy.

They are parsed into validated replacement snapshots and hot-reloaded on the Wayland event loop. Invalid individual values are ignored, and rule parse failures retain the last valid rule snapshot.

The packaged desktop also includes:

aqueousctl, for inspecting windows, outputs, scene nodes, overlay-plane decisions, cursor settings, and live shell state, and controlling windows, workspaces, keyboard layouts, and overview.
A Dank Material Shell settings plugin with typed controls, a draggable monitor canvas, complete stacking and rule editors, named snap-layout and binding controls, raw advanced file editing, validation, stale-write protection, backups, and toolkit typography synchronization.
A shell-native screen-sharing chooser backed by Aqueous’s private desktop portal backend.

Shell integration and IPC

Project source

The source, annotated configuration references, packaging, and development tools live in the Aqueous GitHub repository.