Getting started

Install Halley

Halley targets native Linux Wayland sessions. This page is showing install notes for v0.5.0.

Requirements

Before installing

Halley expects a real Wayland-capable Linux session with native graphics and input access.

DRM/KMS-capable graphics stack with GBM, EGL, and OpenGL support
A seat/session backend through libseat, such as seatd or logind
libinput and udev access on a real TTY for the native backend
Rust and Cargo if building from source

Optional, but commonly useful:

xwayland-satellite for X11 app support
gamescope for wrapping game launches through halleyctl gamescope
xdg-desktop-portal-halley plus xdg-desktop-portal-gtk for portal screenshot, screencast, and common dialog flows
A Wayland terminal if using the default launch bindings
An app launcher such as fuzzel or Halley Lift. Both launch apps; Lift is Halley-native and also searches nodes, clusters, actions, and config over IPC

Arch Linux

AUR packages

Install the stable compositor package with your preferred AUR helper.

yay -S halley
paru -S halley

For the latest source package, use halley-git.

yay -S halley-git
paru -S halley-git

Halley Lift ships separately for users who only want the command palette. The ecosystem bundle, halley-full, installs Halley with Lift and selected first-party ecosystem pieces now; future ecosystem apps such as Aperture will be added there while remaining individually installable.

Command palette

yay -S halley-lift
paru -S halley-lift

Ecosystem bundle

yay -S halley-full
paru -S halley-full

Source

Build with Cargo

Clone the repository and build the release binary locally.

git clone https://github.com/saltnpepper97/halley
cd halley
git checkout v0.5.0
cargo build --release

The compositor binary will be available at target/release/halley.

Startup Options

Help and config selection

Current Halley releases document startup flags through halley --help. Use halley --config to launch with an explicit config file; that path takes precedence over HALLEY_WL_CONFIG, the user config, the system config, and generated defaults.

halley --help

halley --config ~/.config/halley/halley.rune

Nested

Run Halley inside another compositor

v0.5.0 adds halley --nested as the explicit nested launcher. It forces the winit backend, opens a visible host window, creates a nested Wayland socket for test clients, and skips full-session startup behavior such as session autostart.

halley --nested

Display Manager

Launch as a Wayland session

Current Halley releases ship session assets for display managers such as SDDM. When installed from a package, pick Halley from the Wayland session list. The session entry starts Halley through the recommended public session launcher.

halley-session

Packagers, service files, and session wrappers can call the lower-level session flag directly when they already control the surrounding login environment.

halley --session

Desktop Portal

Screenshot and screencast portal setup

v0.5.0 ships Halley's native xdg-desktop-portal-halley backend for ScreenCast and Screenshot requests. Install it with a general portal implementation so apps can request capture and still get file/dialog portal support from GTK.

Packages

xdg-desktop-portal-halley
xdg-desktop-portal-gtk

Session environment

XDG_CURRENT_DESKTOP=Halley
XDG_SESSION_TYPE=wayland

Packaged installs should prefer Halley's portal backend for capture and GTK for other interfaces. If portal capture does not appear after login, restart the user services manually and check the backend with halleyctl portal status.

systemctl --user restart xdg-desktop-portal.service
systemctl --user start xdg-desktop-portal-halley.service

halleyctl portal status