Installation

Aqueous is a Linux Wayland compositor built as a single Zig executable. It has no separate runtime or 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
• Vulkan headers and loader, plus glslang, for the default Vulkan-effects build

Arch Linux

Prebuilt packages are available from CachyOS and the AUR. The package includes Aqueous, aqueousctl, and the session integration; the repository also provides a source PKGBUILD and binary-package recipes for published builds.

CachyOS / Shelly / pacman (Recommended)

Install Aqueous directly from CachyOS repositories.

shelly

shelly -Is aqueous

pacman

sudo pacman -S aqueous

AUR Helpers

Use your preferred AUR helper:

shelly

shelly -Ia aqueous

yay

yay -S aqueous

paru

paru -S aqueous

Build from source

PKGBUILD

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

Build helper

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. The default build uses Aqueous’s Vulkan effects backend; use -Dvulkan-effects=false only when you need the square, no-blur diagnostic build.

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. layout.toml, input.toml, and rules.toml are optional, so create only the files 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. Use aqueousctl windows or aqueousctl inspect --rule after starting a session to discover the exact application identities for window rules.