Installation

Aqueous separates the compositor and configuration tools from the desktop session and shell. The core contains aqueous, aqueousctl, aqueous-config, and the matching private wlroots library. Desktop packages add session startup, portals and shell integration. Only some package families include Welcome.

Package availability varies by repository. Check the package description and version before installing.

Choose a distribution and package family

Devario already includes Aqueous and Pearl. Update it through its configured repositories. Use the Arch instructions below for Arch/CachyOS, not Devario.

On Arch/CachyOS, use your distribution’s published package or the Seafoam Labs repository documented under Pearl installation. Check the desktop selection table for the login entry, shell and configuration folder each package uses.

Arch Linux

Pearl desktop preset

Install the complete Pearl desktop from your configured repository:

shelly install standard aqueous-desktop

This installs the compositor, session, Pearl integration, portal, Pearl, Pearl Greeter and RTKit. Review the greeter change before accepting: it can replace your next boot’s login screen. Select Aqueous at login; an existing user session.toml still overrides the Pearl default. See selecting Pearl.

To build and install this preset from an Arch build environment:

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous/packaging/arch/aqueous-desktop
shelly build --sync-deps --install

Shelly reviews the recipe, builds it as your normal user, and installs all six packages together after a successful build. It requests authorization when needed.

Pearl, its greeter and RTKit must be separately available as dependencies. The recipe fetches its published release tag; it does not automatically build unpublished checkout changes. See the Arch preset contract.

Git: replacement or coexistence

Choose one Git recipe. Both use the same component package names, but install different paths. Do not mix them.

Recipe	Effect
packaging/arch/aqueous-desktop-git	Pearl Git preset replacing stable Aqueous components. Select Aqueous; use standard Aqueous commands and ~/.config/aqueous/.
packaging/arch/aqueous-git	Coexisting Aqueous-Git session with suffixed Aqueous commands and ~/.config/aqueous-git/. Pearl is optional; a fresh desktop starts with no shell.

To build the separate Aqueous-Git desktop:

cd Aqueous/packaging/arch/aqueous-git
package_dir=$(mktemp -d "$PWD/packages.XXXXXX")
shelly build --sync-deps --package-destination "$package_dir"

After a successful build, continue in the same Bash terminal to install the default components, leaving the three optional shell presets out:

mapfile -t packages < <(
    printf '%s\n' "$package_dir"/*.pkg.tar.zst |
        awk '!/\/aqueous-shell-(dms|noctalia|pearl)-git-/'
)
shelly install standard "${packages[@]}"

Install a matching shell preset, such as aqueous-shell-pearl-git, configure the per-instance shell selection and log into Aqueous-Git. For this recipe, do not use shelly build --install: it would install every split output, including all three optional shells.

This family no longer installs Welcome or the standalone GTK source picker. Its live shell-switch command is retired. DMS and shell-free sessions need an explicit sharing chooser; see screen-sharing setup. See the Git packaging guide for details.

Other Arch package variants

• A distribution’s aqueous package can still be the root PKGBUILD component desktop (1.0.5-1), including Welcome and optional shell presets. Follow its installed package description and Welcome flow.
• packaging/arch/aqueous/PKGBUILD is compositor-only; it does not install a desktop session. Likewise, installing a core package alone is not a complete desktop installation.
• PKGBUILD-bin uses matching release component archives and needs a generated recipe with release checksums. Check the actual AUR recipe before building.
• Current x86_64 package builds target x86-64-v3 on Intel and AMD. Older CPUs need a separately built lower-target package; aarch64 uses its baseline. Keep the private wlroots library paired with its compositor.

Fedora

On a mutable Fedora installation, run the installer as your normal user from the repository checkout:

bash scripts/fedora-install.sh

It fetches current upstream master into a separate build directory, installs build dependencies through DNF, and builds a local desktop RPM. It uses sudo for package transactions. Fedora must provide Zig 0.16 or newer and wayland-protocols 1.49 or newer.

Useful options include --build-only, --skip-deps, and --core-only. Core-only mode produces an aqueous-core RPM without desktop session dependencies. The default desktop RPM retains the legacy aqueous-git name; it is distinct from the co-installable Arch Git packaging above. --dms-git explicitly enables the DMS development COPR and cannot be combined with --core-only.

The installer does not support Atomic desktops such as Silverblue/Kinoite or bootc hosts. Existing user configuration is retained; edited system defaults may receive .rpmnew files. See the Fedora source guide for updating, removal, and package prerequisites.

Gentoo

The repository includes an installer that can install dependencies, build the pinned compositor stack and settings helper, install the session, and verify the result:

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
sudo scripts/gentoo-install.sh all

Use deps, build, or install instead of all to run one stage. For the shell-independent core, put --core-only before the stage, for example sudo scripts/gentoo-install.sh --core-only all. Existing files under /etc are preserved; changed packaged defaults are written beside them with an .aqnew suffix.

NixOS

The nix/ directory provides a package, overlay, and NixOS module. From a configuration repository, import both the module and overlay:

{
  imports = [ /path/to/Aqueous/nix/module.nix ];
  nixpkgs.overlays = [ (import /path/to/Aqueous/nix/overlay.nix) ];

  programs.aqueous = {
    enable = true;
    package = pkgs.aqueous;
    shell = "noctalia"; # noctalia | dms | pearl | none
  };
}

Choose programs.aqueous.shell explicitly. DMS and Pearl also require programs.aqueous.shellPackage; Noctalia defaults to pkgs.noctalia-shell. Use "none" for a managed session without a shell. The old noctalia.enable setting is deprecated, and conflicting choices fail validation. An existing per-user session.toml takes precedence over the system default.

programs.aqueous.welcome.enable optionally adds Welcome. Its package-install workflow requires Shelly to be available separately. Installing pkgs.aqueousCore alone installs the tools without enabling the session module.

Build from source

Building requires Zig 0.16 or newer, wayland-protocols 1.49 or newer, wlroots 0.20 build dependencies, libxkbcommon, libinput, libevdev, pixman, Vulkan headers and loader, Meson, Ninja, pkg-config, and glslang. XWayland builds also need the Xwayland executable. Man-page builds use scdoc.

The repository helper builds the patched wlroots render hook and stages aqueous and aqueousctl under bin/:

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

For a direct development build:

cd compositor
scripts/build-wlroots-render-hook.sh
export PKG_CONFIG_PATH="$PWD/.deps/wlroots-render-hook/lib/pkgconfig"
zig build -Doptimize=ReleaseSafe -Dxwayland -Dllvm

Useful build switches are:

Option	Purpose
-Dxwayland=true	Build embedded XWayland support.
-Dvulkan-effects=false	Diagnostic build without Aqueous blur or rounded corners; still requires the pinned patched wlroots.
-Danimations=false	Compile out compositor-side placement and workspace motion.
-Dman-pages=true	Build and install manual pages when scdoc is available.
-Dexternal-policy=true	Build the retired River external-policy path for compatibility testing only.

Caution

The normal effects build requires Aqueous’s pinned wlroots render hook and Vulkan renderer. Keep the installed private wlroots library with the compositor instead of substituting a system wlroots build.

Starting a session

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

2. The packaged wrapper launches Aqueous through UWSM, exports the live WAYLAND_DISPLAY and optional XWayland environment, and starts the graphical-session services and portals.

3. Follow the shell selection for your package family. Current Pearl presets select Pearl; older component desktops can include Welcome; coexisting Git needs an explicit shell selection. Existing user configuration is retained.

Use Desktop selection for package-specific activation, configuration paths, upgrades and recovery. Settings are supplied by Pearl and the canonical configuration helper.

To run a nested development session inside another Wayland compositor:

./launch_aqueous.sh

The launcher starts Aqueous and Pearl in the nested display, using pearl or pearl-git when available. Set AQUEOUS_COMPOSITOR_BIN=/path/to/aqueous to select a build and AQUEOUS_PEARL_CMD to override the shell command. Nested sessions use Alt for the compositor modifier so they do not compete with the host’s Super bindings. Default logs are /tmp/aqueous.log and /tmp/pearl.log.

Runtime switches

aqueous -help lists the complete runtime interface. Common development options include -c <command>, -log-level debug, -no-xwayland, and -xwayland-scaling native. Shipped sessions use the internal policy; external and comparison policy modes require the compatibility build option above.