Installation

Pearl requires Aqueous: packages depend on aqueous>0.7, and the settings integration needs aqueous-config 0.8.2 or newer. The shell package bundles pearl, pearlctl, pearl-lock, pearl-settings, pearl-themes, pearl-agent, the desktop portal backend, and the Phyto, Dome, and Coral companion applications. The login greeter is a separate package that runs on ordinary Aqueous and is independent of the shell.

Seafoam Labs repository (Recommended)

The seafoam-labs repository publishes stable and Git Pearl packages, the optional Qt style package, and Aqueous desktop components. Select the Aqueous package family before installing a shell; Pearl alone does not install a complete session.

Add it to Shelly by following the repository setup instructions. The key import, repository entry and sync commands there are generated from the repository’s published address and current signing key.

Then install:

Pearl shell (Git)

shelly install standard pearl-git

For stable Pearl, install pearl with the matching Aqueous preset. Stable v0.3.0 is available in both Seafoam Labs and Devario core repositories.

Git Pearl uses suffixed commands but shares ~/.config/pearl/ preferences with stable. Choose the Aqueous Git desktop carefully: one replaces stable Aqueous, the other uses a separate session.

Version and distribution differences

These guides follow Pearl main 6cb9b55 and Aqueous 71c0e72, checked October 24, 2026. Both latest releases, Pearl v0.3.0 and Aqueous v1.0.5, were published October 22. Pearl main has newer features; Aqueous packaging has changed since its release.

• Devario: use Shelly and the configured Devario repositories. Images and stable/bleeding-edge channels can contain different versions.
• Arch/CachyOS: use matching desktop components from your chosen repository. Devario repositories are not compatible substitutes.
• Git builds: check the installed revision with pearlctl-git status and your package manager; Git packages can lag behind main.

If a documented control is missing, check the version and helper status before changing configuration. See updates and recovery.

Optional packages

Optional packages in the same repository:

• pearl-greeter-git: the greetd login screen. Installing it selects Pearl Greeter as the display manager for the next boot and backs up an existing /etc/greetd/config.toml. Nothing is restarted; reboot when ready. See the greeter documentation.
• pearl-darkly-style with qtengine: Darkly application styles for shared Qt 5/6 appearance management.

You can browse the full catalog at repo.seafoam-labs.org.

Note

The Devario platform repositories (devario-core and friends) are separate and are not usable on Arch Linux. On Devario, Pearl ships as part of the Devario desktop.

Build from a checkout

Recipe	Packages	Purpose
packaging/arch	pearl	Stable shell built from the published release tag.
packaging/arch-git	pearl-git, pearl-greeter-git	Split Git build from upstream; co-installable with the stable package.
packaging/arch-darkly-style*	pearl-darkly-style variants	Optional Qt Darkly application styles.
packaging/Devario	pearl, pearl-greeter, pearl-git, pearl-greeter-git, devario-desktop	Stable and Git recipes used to build the Devario desktop.

Building requires Zig 0.16.0 exactly, plus git, pkgconf, gcc, qt5-base, qt6-base, Python, rust, rust-wasm, and librsvg; shelly build --sync-deps resolves these together with the GTK 4 runtime libraries.

Build the Git shell and greeter:

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

To install only the greeter, use the greeter build instructions. The Git package suffixes its binaries (pearl-git, pearlctl-git, and so on), so it can coexist with a stable installation. The stable recipe in packaging/arch fetches the release tag, which must be published before the build succeeds.

A plain development build without packaging:

ZIG_GLOBAL_CACHE_DIR="$PWD/.cache/zig" zig build -Doptimize=ReleaseSafe

Optional runtime dependencies

Enable the desktop services you want; Pearl degrades gracefully without them:

Package	Enables
networkmanager	Wi-Fi controls and saved profiles.
bluez	Bluetooth pairing and discovery.
upower	Battery status.
power-profiles-daemon	Power profile switching.
qtengine	Shared Qt 5/6 appearance management.
pearl-assistant-runtime or llama-cpp	Local model runtime for the launcher assistant.
foot, kitty, alacritty, konsole or xterm	Terminal for the assistant’s interactive runtime setup; Arch also needs sudo.
gvfs, file-roller	Phyto file manager extras.
nvidia-utils	NVIDIA GPU metrics in Dome.

Starting a session

1. Install an Aqueous desktop. See the Aqueous installation guide.

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

3. Follow the package-specific Pearl selection. Current Pearl presets select it by default; older component packages may provide Welcome. Existing user selections and personal settings are retained.

Aqueous starts Pearl through the service listed in the instance table. After login, check the launcher, Settings and keyboard layout. If login fails, use greeter recovery.