Getting started

Install Halley

Halley targets native Linux Wayland sessions. This page is showing install notes for v0.7.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 ES 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:

An Xwayland server executable for X11 app support; Halley starts and manages it natively
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 its available first-party ecosystem pieces.

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.7.0
cargo build --release --workspace

The workspace build produces halley, halleyctl, halley-lift, and xdg-desktop-portal-halley in target/release.

Startup Options

Help and config selection

Halley documents startup flags through halley --help. Use -c or --config for an explicit file. Otherwise Halley reads $XDG_CONFIG_HOME/halley/halley.rune, or ~/.config/halley/halley.rune when XDG_CONFIG_HOME is unset, and creates a default file when needed.

halley --help

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

Nested

Run Halley inside another compositor

Use halley --winit to run the rewritten compositor in a visible host window. The nested backend creates its own Wayland socket and skips native-session device ownership and autostart.

halley --winit

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

Halley includes a rewritten 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