Installation

Aqueous targets Linux and Wayland. The compositor, window-management policy, input handling, and output management are compiled into one Zig executable; there is no .NET runtime or separate window-manager service.

Requirements

To build from source, you need:

• Zig 0.16 or newer
• wlroots 0.20, Wayland, wayland-protocols, libxkbcommon, libinput, libevdev, pixman, and pkg-config development files
• XWayland when building with -Dxwayland
• SceneFX when building with -Dscenefx=true

The reference Arch package declares the complete runtime and build dependency set, including the session, portal, XWayland, and Noctalia components.

Arch Linux

The repository includes a source PKGBUILD, plus binary-package recipes for published builds. The source package installs the compositor, aqueousctl, the Wayland session entry, portal integration, the default wm.toml, and Noctalia session assets.

Build the Arch package

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
makepkg -si

Build from source

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
scripts/build-compositor.sh

The build helper stages aqueous and aqueousctl under bin/. For a direct development build, run zig build from the compositor/ directory.

Starting a session

1. Select Aqueous from your display manager’s Wayland session list.

2. The packaged session starts Aqueous through UWSM, exports the live Wayland environment, and starts the graphical-session services.

3. To test a development build inside an existing Wayland session, run:

   ./launch_river.sh

The launcher name is historical

launch_river.sh starts a nested Aqueous session. The project no longer launches a separate River compositor or external window-manager client.

First-run configuration

The packaged session creates ~/.config/aqueous/wm.toml from the system default when the file does not already exist. It never overwrites your copy. The other three files are optional sidecars, so create only the ones you want to customize:

mkdir -p ~/.config/aqueous

# When working from a source checkout:
cp layout.toml.example ~/.config/aqueous/layout.toml
cp input.toml.example  ~/.config/aqueous/input.toml
cp rules.toml.example  ~/.config/aqueous/rules.toml

The example files are heavily annotated references. For a smaller day-to-day setup, use the focused examples in the Configuration guide and add sections only as you need them.