An Arch Linux X11 desktop built for keyboard-driven work

Documentation | Releases | Changelog | Contributing

This is a fork of dwm-titus. It is designed to run on Arch Linux rather than Fedora. Lyona is not a 1-for-1 of dwm-titus Claude is used to help storyboard, build sprints, fix code where needed, and build documentation. CodeRabbit is also used to check code

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 desktop. 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.

Lyona is an X11 desktop. A Wayland-native session is not currently part of the project scope.

The newest release's notes summarize what changed and what is still being qualified: 2026.10.0-beta.5. CHANGELOG.md has the complete list.

Choose the path that matches your system:

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.sh

The image is named for the release it was built from, VERSION in config.mk: out/lyona-VERSION-x86_64.iso. A booted medium reports its exact build in /etc/lyona-iso-release.

Pre-release images are published on the Releases page, each with a lyona-VERSION-SHA256SUMS file. Check the download before writing it; the file also lists the source archive, which --ignore-missing skips when you downloaded only the image:

sha256sum -c --ignore-missing lyona-VERSION-SHA256SUMS

From 2026.10.0-beta.2 on, releases are also signed; the Installation Guide shows how to check the signature.

Write the ISO to a USB drive and boot it, with UEFI or a legacy BIOS. The lyona-install wizard launches automatically. It asks, in menus: the keyboard layout, the disk to erase, btrfs or ext4 with optional LUKS encryption, your user and password, the hostname, the timezone (detected, for you to confirm), and, on an NVIDIA GPU, which driver. Nothing is written until you confirm the summary. It then drives archinstall unattended and finishes installing Lyona. ISO installs get the multilib and CachyOS repositories and the linux-cachyos kernel without being asked; it is the only kernel installed. If the CachyOS repositories cannot be reached, the stock Arch kernel is installed instead; should they work again by the end of the install, linux-cachyos is added as the default and the stock kernel stays beside it. See the Installation Guide for details.

git clone https://github.com/technicks89/Lyona.git
cd Lyona

./install.sh --dry-run --non-interactive --profile recommended
./install.sh --profile recommended

The 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.

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.

With a display manager, select the dwm session when logging in. From a TTY, start the session with:

startx

Most 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
• Updating and Rollback
• 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-diagnostics

You 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 a lyona-update apply leaves you without a working desktop, log in at a TTY (Ctrl+Alt+F2 through F6) and roll back — this does not need Quickshell, D-Bus, or a running polkit agent:

lyona-update rollback --list   # see what is available
lyona-update rollback          # restore the newest backup
startx                         # or log in normally afterward

See Updating and Rollback for the full walkthrough.

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-tests

Project requirements and active work are tracked in SPEC.md, ROADMAP.md, and TASKS.md.