An Arch Linux X11 desktop built for keyboard-driven work
This is a fork of dwm-titus. It is designed to run on Arch Linux rather than Fedora. lyona also draws inspiration from Omarchy.
lyona is a complete, lightweight X11 desktop with sensible defaults, guided installation, and powerful customization. It is designed for people who want a responsive keyboard-first workflow without having to assemble every part themselves.
lyona is an Arch Linux-only distribution. Arch Linux is the sole supported platform for installation, runtime behavior, package resolution, testing, and release qualification. Use either the Arch installer image or the existing-system installer on Arch Linux.
| Experience | What it includes |
|---|---|
| A focused desktop | Automatic window tiling, nine workspaces, fast keyboard navigation, multi-monitor support, and flexible fullscreen modes. |
| Everyday essentials | A polished panel, application launcher, system tray, Control Center, Settings, notifications, screenshots, audio, brightness, and power controls. |
| Easy discovery | An interactive keybind viewer, guided display setup, built-in diagnostics, and clear unsupported-feature reporting. |
| Personal configuration | Live-reloading hotkeys, themes, and window rules, with local configuration preserved across upgrades. |
| Panel customization | Show or hide individual panel widgets (workspace, volume, Bluetooth, network, power) from Settings, with the choice persisted across every monitor and a fresh session. |
| Two installation paths | A ready-to-install Arch image or an installer for an existing Arch system. |
lyona is an X11 desktop. A Wayland-native session is not currently part of the project scope.
Highlights from the last few development phases. See CHANGELOG.md for the complete, unabridged list.
- Show or hide individual panel widgets (workspace, volume, Bluetooth, network, power) from Settings, persisted across every monitor and a fresh session.
- Settings now reports accessibility maturity per capability — text scale, contrast, reduced motion, notification policy, and keyboard/pointer access — instead of a single all-or-nothing accessibility state.
- The Settings window was resized and its navigation, panes, and display controls tightened, so more options stay visible without shrinking your configured text scale.
- Fixed a
Super+AChatGPT/webapp launch that never found a user-scoped browser install; it now correctly prefers an installed desktop app and falls back to the web app only when asked to. - Fixed
dwm-settings-inputsilently reporting zero input devices whenxinputfailed outright, instead of surfacing the failure. - Fixed a rare race in the appearance inventory scanner that could lose track of an in-progress scan.
- Closed the last installer paths that could pipe an unverified remote
script into
sudo sh, or build an unpinned clone as root (the Starship, fzf, zoxide, andyay-binfallbacks). xscreensaver-based screen blanking is now wired into the real lock chain, so it actually locks the session instead of just going dark.- The CachyOS package-signing key is now fingerprint-verified before it's trusted, instead of trusting whatever a keyserver returns for its key ID.
dwmnow builds with standard compiler hardening (stack protector, PIE, RELRO, fortified source, format-security warnings).- Closed a
.desktop-file injection path inwebapp-createand added a dedicated polkit consent prompt for display-settings changes.
Choose the path that matches your system:
| Installation | Best for | What it does |
|---|---|---|
| Arch ISO | A fresh, dedicated installation | Boots a live Arch image with this checkout preloaded for a guided install. |
| Existing system | An Arch installation you already use | Installs dependencies, the desktop session, and the selected feature set while preserving local configuration. |
For complete requirements and installation details, see the Installation Guide.
Build the installer image from this checkout (requires the archiso
package, on an Arch host):
sudo scripts/build-lyona-arch-iso.shThe image is named for the release it was built from, so the current
checkout produces out/lyona-2026.08.0-x86_64.iso. A booted medium
reports its exact build in /etc/lyona-iso-release.
Write the resulting ISO to a USB drive and boot it (UEFI only). The
lyona-install wizard launches automatically — arrow-key menus for
disk/keyboard, a few prompts for user/hostname/timezone, no
desktop-environment picker — then drives archinstall unattended and
automatically finishes installing lyona. ISO installs get the multilib
and CachyOS repositories and both the linux-cachyos
and linux-cachyos-lts kernels without being asked; the stock Arch kernel
stays the default boot entry, so the CachyOS ones are there to select, not
to surprise you. See the
Installation Guide for details.
No prebuilt ISO is currently published as a release; build one yourself
with the script above.
git clone https://github.com/technicks89/Lyona.git
cd Lyona
./install.sh --dry-run --non-interactive --profile recommended
./install.sh --profile recommendedThe dry run shows the dependency and installation plan before anything changes.
The installer requires Arch Linux, preserves existing personal configuration,
and installs the managed desktop components. It accepts only Arch's
/etc/os-release identity and rejects every other operating-system identity
before making changes.
| Profile | Includes |
|---|---|
core |
The X11 session, required dependencies, and one terminal emulator. |
recommended |
The complete everyday desktop, including Alacritty, Quickshell, Gear Lever for AppImages, theming, screenshots, audio, and brightness tools. |
full |
The recommended desktop plus optional file-manager, keyring, wallpaper, display-manager, and supported Arch gaming integrations (Steam, Gamescope, GameMode, MangoHud via multilib). |
On x86_64, --enable-cachyos-repos adds the CachyOS
repositories for this CPU's ISA level, and --cachyos-kernel also installs
linux-cachyos and adds a boot entry for it. Both are opt-in, ask before
touching pacman.conf, and back it up first; see the
Installation Guide for what they
change.
maim is an optional dependency used only by the screenshot hotkeys. If it is
unavailable, installation continues and reports that the screenshot hotkeys
remain disabled; invoking one makes dwm-screenshot exit with
dwm-screenshot: maim is not installed. xclip and xdotool remain required
runtime dependencies for the X11 desktop and its other managed helpers.
Super is the Windows key on most keyboards.
| Action | Keybind |
|---|---|
| Open the application launcher | Super + R |
| Open Alacritty terminal | Super + X |
| Open Control Center | Super + F1 |
| Show the interactive keybind viewer | Super + / |
| Close the focused window | Super + Q |
| Switch workspace | Super + 1-9 |
| Open the power menu | Super + Ctrl + Q |
With a display manager, select the dwm session when logging in. From a TTY,
start the session with:
startxMost personal settings live under:
${XDG_CONFIG_HOME:-$HOME/.config}/lyona/
Hotkeys, themes, and window rules reload when their TOML files are saved.
Advanced compile-time preferences live in the user-owned config.h, which the
installer and future upgrades preserve.
The installer also provides dwm-settings-display and its root-owned
libexec/lyona/dwm-settings-display-root persistence helper. Live display
discovery and previews require xrandr; hotplug watching requires udevadm;
only persistent Xorg install and rollback require pkexec. Named profiles live
under the display-profiles/ directory in the XDG path above.
Run dwm-display-setup detect, then dwm-display-setup, for a guided wizard
that detects outputs and configures modes, positions, rotation, and the primary
display with a reversible preview. Persistent generation selects compatible
TearFree or NVIDIA Full Composition Pipeline behavior automatically; pass
--force-full-composition-pipeline off to disable the NVIDIA default.
The adjacent dwm-settings-input provider uses xinput, setxkbmap for
keyboard settings, and udevadm for stable device identity and hotplug events.
Kept values are stored in input-settings.conf in the same XDG directory;
DWM_INPUT_SETTINGS_FILE can select another file.
Settings also reports accessibility maturity per capability — text scale, contrast, reduced motion, notification policy, and keyboard/pointer access — instead of a single all-or-nothing accessibility state, so it's clear which of these are already usable and which are still read-only reporting on your system.
See the Configuration Guide and Theming Guide for examples and safe customization paths.
- Installation
- Getting Started
- Keybindings
- Configuration
- Theming
- Control Center
- Settings
- How lyona Works
- Troubleshooting
The technical guide explains the project architecture, what dwm is, and how the maintained enhancements fit together. You do not need to understand or apply dwm patches to install and use the desktop.
Start with the built-in diagnostic report:
dwm-diagnosticsYou can also open Control Center -> System Health for a graphical overview.
If the session does not start, run startx from a TTY to see its error output.
The Troubleshooting Guide
covers common session, panel, terminal, theme, display, and NVIDIA issues.
If the problem remains, open an issue and include the relevant diagnostic output. Review it first and remove any private system information.
Contributions are welcome. Read CONTRIBUTING.md for the development workflow and validation requirements, and report security issues using SECURITY.md.
The main repository check uses a managed workspace under $HOME/tmp and
removes it when the run finishes:
scripts/run-testsProject requirements and active work are tracked in SPEC.md, ROADMAP.md, and TASKS.md.