Getting started

Install Halley

Halley targets native Linux Wayland sessions. This page is showing install notes for v0.4.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-wlr plus xdg-desktop-portal-gtk for portal screenshot and screencast flows
  • fuzzel and a Wayland terminal if using the default launch bindings

Arch Linux

AUR packages

Install the stable package with your preferred AUR helper.

yay 
yay -S halley
paru 
paru -S halley

For the latest commit, install the development package.

yay dev 
yay -S halley-dev
paru dev 
paru -S halley-dev

Source

Build with Cargo

Clone the repository and build the release binary locally.

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

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

Startup Options

Help and config selection

v0.4.0 documents 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.

help 
halley --help
explicit config 
halley --config ~/.config/halley/halley.rune

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.

session entry 
halley-session

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

session wrapper 
halley --session

Desktop Portal

Screenshot and screencast portal setup

Halley exposes the wlr screencopy protocol used by xdg-desktop-portal-wlr. Install the portal backend plus a general portal implementation so apps can request screen capture through the standard desktop portal APIs.

Packages
packages 
xdg-desktop-portal-wlr
xdg-desktop-portal-gtk
Session environment
environment 
XDG_CURRENT_DESKTOP=Halley
XDG_SESSION_TYPE=wayland

When Halley starts its native tty session, it exports the Wayland and desktop environment to D-Bus/systemd and queues a restart of xdg-desktop-portal.service plus a start of xdg-desktop-portal-wlr.service. If portal capture does not appear after login, restart those user services manually.

portal services 
systemctl --user restart xdg-desktop-portal.service
systemctl --user start xdg-desktop-portal-wlr.service