Arch Installation

lyona is Arch Linux-only. Arch Linux with Xorg is required for every supported installation, package, test, and release path.

Install

1. Dependencies

The supported dependency path is the installer because it resolves Arch package names from the shared map:

./install.sh --dry-run --non-interactive --profile core
./install.sh --profile full

Use core for the required build/X11/session packages and Alacritty, recommended for the complete desktop layer, or full for optional extras such as file-manager integration, keyring login integration, wallpapers, and display-manager setup. On x86_64 Arch, full can also install Steam, Gamescope, GameMode, and MangoHud after repository approval. The installer separately asks before enabling the multilib repository for Steam, Gamescope, GameMode, and MangoHud. Declining skips the gaming subset without affecting other full-profile extras.

2. Clone and Build

git clone https://github.com/technicks89/dwm-titus.git lyona
cd lyona
cp config.def.h config.h
./scripts/dev-sync-install.sh

For later source-checkout updates, run the same command so the binary, installed helpers, managed Quickshell configuration, and data copy stay at one revision. Run ./scripts/dev-sync-install.sh --check after any requested session restart to verify the active runtime.

Automated Installer

./install.sh

The script requires ID=arch before handling dependency installation, font copying, display-manager integration, or config placement. Every other operating-system identity is rejected before changes are made. Existing user configuration and .xinitrc files are preserved. Upgrades remove the known legacy dwm-graphical-session.service and wm-graphical-session.service early-start configuration so XDG applications start only after the X11 display environment is available; customized user units are disabled from early startup but otherwise preserved.

System files are installed with sudo, while configuration and data under the user’s XDG directories are installed as that user.

Every profile and Arch image defaults to Alacritty without Herdr. With the explicit --install-herdr option, the repository downloads the official https://herdr.dev/install.sh into an isolated staging directory and verifies repository-pinned SHA-256 checksums for both that installer and its resulting Herdr binary before copying it into ~/.local/bin. A checksum mismatch or network failure leaves Alacritty usable and reports the Herdr failure. When the codex or claude command is already available, the helper also runs Herdr’s matching integration install command so native Codex and Claude Code sessions can be restored. Integration failures are reported separately from binary installation failures.

When matching vendor XDG entries exist for Picom, the polkit agent, or Light Locker, the installer copies each entry to the user autostart directory and adds only the dwm session exclusion. Original commands and vendor session guards remain intact, no entry is created when the vendor entry is absent, and existing user entries are preserved.

Installer package profiles are selected with DWM_INSTALL_PROFILE:

• core: required build packages, X11/session runtime, and Alacritty. Herdr is skipped unless --install-herdr is provided.
• recommended: core plus the recommended desktop layer such as Quickshell, Picom, Feh, Dex, fonts, theming, screenshot, audio, Bluetooth control and tray tools, brightness tools, Flatpak, and the GTK desktop portal. It also adds Flathub for the target user, installs Gear Lever as the default AppImage manager, and installs the available Arch GTK theme packages. A matching GTK theme is generated for every palette in config/themes.toml, so GTK applications follow the active theme without a downloaded theme pack. It also installs the mybash shell configuration: a Starship prompt, Fastfetch, fzf and zoxide, cloned into ~/.local/share/mybash and linked from ~/.bashrc, ~/.config/starship.toml, ~/.config/fastfetch/config.jsonc, and ~/.local/bin/starship-theme. An existing ~/.bashrc is kept as ~/.bashrc.bak. The clone is replaced on every run, so edit the files it links to rather than the clone itself.
• full: recommended plus optional extras such as Thunar with SMB-share browsing, network tray utilities, keyring login integration, wallpapers, and display-manager setup. x86_64 Arch full installs also include Steam, Gamescope, and 64-bit and 32-bit GameMode and MangoHud support after separate repository approval. The installer enables the multilib repository for Steam, Gamescope, GameMode, and MangoHud, then adds the invoking user to the gamemode group; log out and back in before using its privileged tuning helpers.

The default is full to preserve the historical automated installer behavior. If maim is unavailable in the enabled Arch repositories, the installer skips that add-on instead of failing the desktop install and reports that the screenshot hotkeys are unavailable.

For a minimal install:

DWM_INSTALL_PROFILE=core ./install.sh

The same profile can be selected with a flag:

./install.sh --profile core

Interactive runs print the resolved package plan before prompting. For CI, packaging checks, or scripted validation, use the non-interactive flags:

./install.sh --dry-run --non-interactive --profile core
./install.sh --non-interactive --yes --profile recommended
./install.sh --non-interactive --yes --profile full --enable-arch-gaming-repos
./install.sh --non-interactive --yes --profile full --cachyos-kernel

Without --enable-arch-gaming-repos, unattended Arch full installs skip Steam, Gamescope, GameMode, and MangoHud rather than changing repository trust. An already-enabled multilib counts as approval, since nothing in pacman.conf has to change – this is what installs from the lyona ISO get, because the ISO ships multilib enabled.

CachyOS repositories and kernel

Installs from the lyona ISO get this automatically and are not asked about it. The repositories are added to the live medium before archinstall runs, so pacstrap fetches the optimized packages directly instead of installing Arch builds and replacing them afterwards – the base system is downloaded once, not twice. The installed system inherits the live medium’s pacman.conf along with the CachyOS mirrorlists and keyring, and the postinstall step then installs linux-cachyos and linux-cachyos-lts. The stock Arch kernel remains installed and remains the default boot entry – the CachyOS kernels are added to the boot menu for you to select. If the CachyOS mirror cannot be reached, the install continues on the stock Arch repositories instead of failing.

On an existing system, the installer can do the same, but both steps are opt-in and are never enabled by default:

./install.sh --profile full --enable-cachyos-repos
./install.sh --profile full --cachyos-kernel

--cachyos-kernel implies --enable-cachyos-repos. Interactive runs ask for both separately; DWM_INSTALL_CACHYOS_REPOS=true and DWM_INSTALL_CACHYOS_KERNEL=true are the environment equivalents.

Adding the repositories imports and locally signs the CachyOS signing key, installs the CachyOS keyring and mirrorlists, replaces pacman with the CachyOS build that understands the ISA-specific mirrorlists, adds the repository set matching this CPU (znver4, x86-64-v4, x86-64-v3, or the plain cachyos repository) above [core], and upgrades the system to the optimized packages. pacman.conf is backed up first and restored if any step fails.

The kernel step installs linux-cachyos and makes it bootable: GRUB configurations are regenerated, and systemd-boot installs get a copy of the existing loader entry pointing at the new kernel image. Any other bootloader is reported so the entry can be added by hand. The existing kernel is left installed and bootable.

Kernel headers are only needed to build out-of-tree modules, so they are not installed by default. Pass --with-headers to lyona-cachyos install-kernel to include them; they are also included automatically when DKMS is already present, which is what the NVIDIA driver path relies on.

The same steps are available on their own afterwards:

lyona-cachyos status
lyona-cachyos add-repos              # --no-upgrade to skip the system upgrade
lyona-cachyos install-kernel         # --with-headers to include kernel headers

Herdr is skipped for every profile unless --install-herdr or DWM_INSTALL_HERDR=true is provided. Its published Linux binaries support x86_64 and aarch64. Installation alone does not change the terminal default; set DWM_HERDR=1 and run dwm-terminal to enter the optional workspace. Herdr can also be installed or repaired separately:

install-herdr
install-herdr --force

Upgrades preserve an existing hotkeys.toml. If an earlier installer seeded its terminal variable to dwm-terminal, set it to alacritty to adopt the current direct-terminal default. The installer does not overwrite that user-owned choice.

An AUR helper (yay) is installed automatically for you as a standing convenience tool, independent of the package profiles above — none of the required, recommended, or optional packages need it, since everything the installer selects is available directly through official pacman repos (core/extra/multilib).

GRUB boot menu theme

The installer ships the CyberRe GRUB theme and selects it by default on machines that boot with GRUB, so the boot menu matches the rest of the desktop instead of the stock text list.

Installing the theme files (make install-system) changes nothing about booting — they are just data under /usr/share/grub/themes/CyberRe. Selecting the theme is a separate step, because it edits the bootloader:

• /etc/default/grub is copied to /etc/default/grub.lyona-backup-<timestamp> before the first edit.
• GRUB_THEME is pointed at the installed theme.
• GRUB_TERMINAL_OUTPUT is commented out if present. GRUB draws themes only on gfxterm, so a console setting would leave the theme installed and invisible.
• GRUB_GFXMODE is set to auto if it is not already set, since the 640x480 fallback letterboxes the theme’s 1920x1080 background.
• grub-mkconfig regenerates /boot/grub/grub.cfg.

Every one of those is printed as it happens. Replaced lines are commented out rather than deleted, so the previous values stay readable in the file next to the backup.

Machines that do not boot with GRUB — including the lyona ISO’s own installs, which use systemd-boot — are reported and left completely alone. A theme step that fails does not fail the install.

Skip the bootloader edit with --skip-grub-theme (or DWM_INSTALL_GRUB_THEME=false); the theme files are still installed, so it can be selected later.

Manage it afterwards with:

lyona-grub-theme status    # detected bootloader and selected theme
lyona-grub-theme list      # installed themes
lyona-grub-theme apply     # select CyberRe (or apply <name>)
lyona-grub-theme remove    # back to the default GRUB appearance

The theme is vendored from ChrisTitusTech/bootloader-themes (MIT) so it is available during an offline install.

Starting dwm

Display manager (SDDM, GDM, LightDM): log out and select dwm from the session list.

When the interactive installer runs inside an active X11 session, it offers the dwm-display-setup wizard after installation. The wizard previews the chosen resolution and multi-monitor layout, then installs a backed-up Xorg fragment. Installations run from a TTY or in non-interactive mode defer this step; after the first X11 login, run:

dwm-display-setup

The installed Settings display provider is machine-oriented. Its actions are:

dwm-settings-display discover
dwm-settings-display watch
dwm-settings-display save NAME SPEC...
dwm-settings-display preview TOKEN SECONDS SPEC...
dwm-settings-display preview-profile TOKEN SECONDS NAME
dwm-settings-display keep TOKEN [NAME]
dwm-settings-display revert TOKEN
dwm-settings-display preview-status [TOKEN]
dwm-settings-display install-profile NAME
dwm-settings-display rollback-system

Discovery and live previews require xrandr, and the hotplug watch requires udevadm. Persistent install and rollback additionally require pkexec plus the root-owned helper installed at ${PREFIX}/libexec/lyona/. Profiles are stored under ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/display-profiles/. No move is needed for profiles created by dwm-display-profile, which uses the same directory. If DWM_DISPLAY_PROFILE_DIR previously pointed elsewhere, either keep that environment override or move those .conf files into the default directory before using Settings.

The input provider exposes the corresponding session actions:

dwm-settings-input discover
dwm-settings-input watch
dwm-settings-input watch-apply
dwm-settings-input apply-saved
dwm-settings-input preview TOKEN SECONDS DEVICE SETTING VALUE
dwm-settings-input keep TOKEN
dwm-settings-input revert TOKEN
dwm-settings-input preview-status [TOKEN]
dwm-settings-input reset DEVICE SETTING

All input actions require xinput; keyboard layout and modifier operations also require setxkbmap; stable hardware identity and hotplug watching use udevadm, and the session watcher uses flock from util-linux to prevent duplicate replay workers. Kept values default to ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/input-settings.conf. Set DWM_INPUT_SETTINGS_FILE to use a different file. The normal session startup invokes apply-saved idempotently and runs watch-apply to debounce input hotplug events before replaying saved values for returning devices.

startx:

startx

The provided .xinitrc disables screen blanking, starts the configured Quickshell panel, and runs dwm.

Minimal Session Profile

The minimal supported profile is useful for lean Arch systems, recovery sessions, and minimal Arch qualification. It keeps only:

• an X11 server and either a display-manager session or startx
• D-Bus session support
• dwm
• Alacritty as the default terminal, with dwm-terminal available to delegated tools that require fallback selection
• required X11 helpers used by core startup and display commands, such as xrandr, xset, and xsetroot

Quickshell, Picom, Feh, Dex, a polkit agent, screenshot tools, wallpapers, tray utilities, and audio or brightness helpers are optional in this profile. Missing optional components should appear as degraded features in dwm-diagnostics, not as session-fatal failures.

For startx, a minimal .xinitrc can be:

#!/bin/sh
xset s off
xset -dpms
xsetroot -cursor_name left_ptr
exec dbus-run-session dwm

If the login path already creates a user D-Bus session, use exec dwm instead of wrapping it with dbus-run-session.

After installation, verify the profile with:

dwm-diagnostics
dwm-terminal --print-command

dwm-diagnostics must report zero required failures before treating the minimal profile as ready. Optional degraded features can remain unresolved. The default binding opens Alacritty directly. A plain dwm-terminal also opens the selected emulator directly unless DWM_HERDR=1 explicitly enables Herdr. Commands such as dwm-terminal -e sh -c 'command' always bypass Herdr.

Getting Started

lyona is an Arch Linux-only X11 desktop. These instructions assume a supported Arch installation completed through the Arch install medium or install.sh.

After installing, the first thing to know: Super = the Windows key.

Press Super + / at any time to open the interactive keybind viewer.

Essential Actions

Switching Tags (Workspaces)

Tags 1-9 act as workspaces. Use Super + a number from 1 through 9 to switch. Super + 0 shows windows from all nine tags at once; 0 is not a tenth tag.

Layouts

Three layouts are available — switch between them instantly.

See Keybindings for the full reference.

Keybindings

Press Super + / inside dwm to open a live, searchable Quickshell keybind viewer.

MODKEY = Super (Windows key) in the shipped config.h.

Bindings are defined in config/hotkeys.toml and reload instantly on save — no recompile needed.

Launchers

Screenshots

All dwm-screenshot capture modes omit the mouse cursor. maim region captures start selection immediately without a monitor chooser. The active-monitor shortcut uses the monitor under the pointer. Clipboard captures are PNG selections owned by xclip, while captures saved to disk use JPEG. The lightweight capture flow intentionally has no annotation toolbar.

Applications and Web Apps

Super + A opens an installed ChatGPT desktop application when one is available and falls back to the ChatGPT web app otherwise. The application launcher hides the ChatGPT web entry while a native desktop entry is installed.

Window Management

Layouts

Tags (Workspaces)

Multi-Monitor

Media Keys

Session & Power

Mouse

Customizing Keybinds

Edit config/hotkeys.toml — changes take effect on save, no recompile required.

[vars]
terminal = "alacritty"

keys = [
  { mod="SUPER SHIFT", key="f", desc="Firefox", func="spawn", exec=["firefox"] },
]

See the comments in hotkeys.toml for a full list of func values and modifier syntax.

The browser binding uses dwm-default-apps open. Configure it with Settings -> Defaults or with dwm-default-apps browsers and dwm-default-apps set-browser <desktop-id>.

The terminal variable defaults to Alacritty. Settings -> Defaults can select a validated installed terminal without changing the Super+X key record. To use the optional Herdr workspace, install it explicitly, change the binding to dwm-terminal, and set DWM_HERDR=1 in the session environment.

Configuration

lyona keeps user configuration under ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/. Hotkeys and themes live-reload on save — no recompile needed for most changes.

For deeper changes (window rules, fonts, refresh rate), edit config.h and run the complete developer synchronization command:

./scripts/dev-sync-install.sh

It rebuilds dwm, updates all installed commands and managed Quickshell/data files when needed, verifies parity, and reports whether the dwm session must be restarted. When a session restart is already required, it activates Quickshell there so the tray host starts before tray clients. Use ./scripts/dev-sync-install.sh --check for a non-mutating audit.

config.h Essentials

config.h is your personal copy of config.def.h. It is created automatically by make if it doesn’t exist.

$EDITOR config.h
./scripts/dev-sync-install.sh

Key Options

Window Rules

Rules in config.h let you assign windows to specific tags or force float:

/* class      instance  title   tags mask  isfloating  isterminal  noswallow  monitor */
{ "Gimp",     NULL,     NULL,   0,         1,          0,           0,        -1 },
{ "Firefox",  NULL,     NULL,   1 << 1,    0,          0,          -1,        -1 },

hotkeys.toml — Live Keybinds

Add or change bindings without recompiling. Save the file and they apply instantly.

[vars]
terminal = "alacritty"
webapp   = "webapp-launch"

keys = [
  { mod="SUPER",       key="x",  desc="Terminal",    func="spawn", exec=["$terminal"] },
  { mod="SUPER SHIFT", key="f",  desc="Firefox",     func="spawn", exec=["firefox"] },
]

The default binding launches Alacritty directly. The dwm-terminal helper is available to delegated tools that need a terminal selection fallback; it also prefers Alacritty and opens the emulator directly by default. Explicit arguments such as dwm-terminal -e command retain their direct execution contract.

Thunar’s seeded Open Terminal Here action launches Alacritty directly in the selected directory, matching the normal Super + X default. Existing Thunar custom actions are preserved during installation and upgrades.

Set DWM_TERMINAL to choose another emulator for dwm-terminal. Herdr is an optional layer: install it explicitly, set DWM_HERDR=1, and run dwm-terminal. Set DWM_HERDR_COMMAND to select a different Herdr binary.

Default applications use freedesktop settings. Run dwm-default-apps browsers to list browser desktop files, dwm-default-apps set-browser firefox.desktop to set the default browser, or dwm-default-apps set-mime <mime> <desktop-id> for other file types.

Display profiles are optional files under ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/display-profiles. Use dwm-display-profile template to print the format, dwm-display-profile list to show profiles, and dwm-display-profile apply <name> to run the profile through xrandr.

For persistent Xorg configuration, run dwm-display-setup. The interactive wizard detects connected outputs and their exact advertised timings, then asks for resolution, refresh rate, rotation, absolute position, and the primary display. It checks whether the active Xorg driver exposes compatible TearFree support or the NVIDIA Full Composition Pipeline and enables only the compatible default. The proposed layout is applied as a live preview and automatically restored unless it is confirmed. Advanced calls may pass --force-full-composition-pipeline off to disable the NVIDIA default; forcing it on with an incompatible kernel or Xorg driver is rejected.

Accepted layouts are installed as the isolated managed fragment /etc/X11/xorg.conf.d/90-lyona-display.conf; existing Xorg files are not replaced. Each change creates a versioned backup. Use dwm-display-setup rollback to restore the newest backup, or dwm-display-setup status to inspect the managed file and current layout. Advanced users can pass an existing display-profile file to dwm-display-setup generate, preview, or install. For noninteractive session changes, dwm-display-setup capture prints the current complete RandR profile, dwm-display-setup validate <profile> checks a profile with xrandr --dryrun, and dwm-display-setup apply <profile> changes the current X11 layout after validation.

The Settings Displays page uses the same profile grammar and validation through dwm-settings-display. Named profiles remain user-owned under the XDG path. Installing one persistently requires explicit confirmation and authorization; only the root-owned helper under ${PREFIX}/libexec/lyona/ may update the managed Xorg fragment. Legacy profiles that omit complete position or rotation state remain usable with dwm-display-profile, but Settings will not preview or install them until they are resaved as a complete layout.

Per-device input values kept in Settings are stored in ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/input-settings.conf. The event-driven input provider uses a hardware serial or path when available, re-resolves that identity before every change, and skips a disconnected device rather than applying its settings to another XInput ID. Session startup runs dwm-settings-input apply-saved and starts an event-driven, debounced hotplug replay so returning devices regain saved values. Repeating the apply is safe. The replay watcher is scoped to the owning dwm process and exits at logout, including when dwm was launched through startx.

Power settings are managed from Control Center -> Power. The generated power.conf is authoritative once created and persists screen DPMS state, display-off timing, and automatic idle and suspend locking. Startup reapplies this file before background session services are launched. Manual locking remains available when automatic locking is disabled. The screen locker runs only while automatic locking is enabled or for the duration of an explicit manual lock, so DPMS display-off events remain independent from locking. External loginctl lock-session requests are forwarded to dwm-lock by an event-driven session listener. Until power.conf exists, lyona leaves any user or Arch-managed locker untouched.

Modifier Syntax

Use space-separated modifiers: "SUPER", "SUPER SHIFT", "SUPER CTRL", "SUPER CTRL SHIFT".

Available Functions

Tag Bindings

Tag bindings auto-generate all four variants (switch, toggle-view, move, toggle-tag):

tag_keys = [
  { key="1", tag=0 },
  { key="2", tag=1 },
]

Notes on XDG Autostart

Recommend using Flatpak to install programs on startup:

flatpak install flathub io.github.flattool.Ignition

or you can create your own .desktop file in ~/.config/autostart/

set-refresh.desktop Example:

[Desktop Entry]
Type=Application
Exec=xrandr --output HDMI-0 --primary --mode 1920x1080 --pos 0x0 --rotate normal --rate 120 --output DP-0 --off --output DP-1 --off --output DP-2 --off --output DP-3 --off --output DP-4 --off --output DP-5 --off
Hidden=false
X-GNOME-Autostart-enabled=true
Name=Set Refresh

Theming

Themes are defined in config/themes.toml. Change the active theme and save to update dwm, Quickshell, terminal, GTK, and Qt styling. No restart needed.

[active]
theme = "tokyonight"   # ← change this line to switch themes

The managed transaction helper is the safe command-line interface for theme changes:

dwm-settings-theme preview preview-1 15 dracula
dwm-settings-theme keep preview-1       # confirm before the timeout
dwm-settings-theme revert preview-1     # or restore immediately
dwm-settings-theme abandon preview-1    # accept a conflicting external edit
dwm-settings-theme apply gruvbox
dwm-settings-theme reset                # restore the managed default selection

An unconfirmed preview restores the exact previous themes.toml bytes and mode automatically. Apply and reset preserve comments, custom theme sections, and unrelated appearance settings. If an operation is interrupted after its atomic write, inspect and restore it with:

dwm-settings-theme recovery-status
dwm-settings-theme recover

Recovery refuses to overwrite an externally changed theme file.

Available Themes

Dark

Light

Border Size

[appearance]
borderpx = 1   # 0 = no border, 1 = thin (default), 2-3 = thicker

What Each Theme Controls

Each [theme.name] section sets colors for all components:

Quickshell derives its opaque surfaces, text, borders, accent, success, warning, and danger colors from the active theme’s existing dwm and terminal color keys.

Creating a Custom Theme

Add a new section to themes.toml:

[theme.mytheme]
normfgcolor     = "#cdd6f4"
normbgcolor     = "#1e1e2e"
normbordercolor = "#313244"
selfgcolor      = "#cdd6f4"
selbgcolor      = "#89b4fa"
selbordercolor  = "#89b4fa"

term_bg         = "#1e1e2e"
term_fg         = "#cdd6f4"
term_cursor     = "#f5e0dc"
# ... term_color0-15 ...
dark_mode       = true
gtk_theme       = "Lyona-mytheme"

Then set theme = "mytheme" under [active] and save.

gtk_theme may name any installed GTK theme. Leaving it out is usually the right choice: make install generates a Lyona-<name> GTK theme from every palette in this file, and that generated theme is what a palette falls back to. Regenerate one by hand with:

scripts/lyona-gtk-theme generate mytheme config/themes.toml ~/.local/share/themes/Lyona-mytheme

Applications built on libadwaita ignore custom GTK themes by design and stay in their own light or dark palette regardless of this setting.

Applying Themes via Control Center

Open the Control Center with Super + F1, navigate to Appearance → Select Theme, and pick from the list. The theme switches immediately.

Wallpapers

Place images in ~/Pictures/backgrounds/. Open Settings → Appearance to select an image, choose its fit, preview it for 30 seconds, apply it, or reset to the random session default. Use Super + Shift + W or dwm-settings-wallpaper randomize for a one-off random wallpaper in the current session, or persist a specific image and fit from a terminal:

dwm-settings-wallpaper apply "$HOME/Pictures/backgrounds/mywall.jpg" fill

Supported fit modes are center, fill, max, scale, and tile. Preview a choice for 30 seconds before keeping it:

token="wallpaper-$$"
dwm-settings-wallpaper preview "$token" 30 \
  "$HOME/Pictures/backgrounds/mywall.jpg" max
dwm-settings-wallpaper keep "$token"

Use dwm-settings-wallpaper reset to return to the session’s random-fill default. If a saved image is removed, login remains usable and falls back to that default until another image is selected or the setting is reset.

Fonts and Text Size

Open Settings -> Appearance to select an installed Fontconfig family and a managed shell text scale from 80, 90, 100, 110, 125, or 150 percent. The icon font remains the shipped Meslo Nerd Font even when ordinary interface text uses another family, so changing fonts cannot remove panel or menu glyphs.

Preview changes for 30 seconds before keeping them, or apply and reset from a terminal:

token="font-$$"
dwm-settings-font preview "$token" 30 "Noto Sans" 1.25
dwm-settings-font keep "$token"

dwm-settings-font apply "Noto Sans" 1.10
dwm-settings-font reset

The setting owns only font.conf under the lyona XDG configuration directory. A malformed file falls back to the existing Meslo family at 100 percent without preventing shell startup. GTK and Qt application font policy is intentionally deferred to the separate toolkit-control slice.

Boot Menu

The GRUB boot menu uses the CyberRe theme, selected by the installer on machines that boot with GRUB. It is not part of the palette system above – GRUB reads its own theme long before the session starts, so it does not follow the dark/light theme you pick in Settings.

lyona-grub-theme status    # detected bootloader and selected theme
lyona-grub-theme list      # installed themes
lyona-grub-theme apply     # select CyberRe (or apply <name>)
lyona-grub-theme remove    # back to the default GRUB appearance

Applying or removing a theme edits /etc/default/grub and regenerates /boot/grub/grub.cfg, so it needs root and backs the file up first. See Install for exactly which keys it changes.

Machines that boot with systemd-boot – which includes installs made from the lyona image – have no GRUB menu to theme, and the commands above report that and do nothing.

Control Center

The Control Center is a single-card anchored Quickshell menu for launching applications, panel settings, system health, quick actions, appearance settings, power management, and keybind discovery.

Open: Super + F1, or run dwm-controlcenter from a terminal.

The popup opens from the panel logo. Applications, Power, Settings, System Health, Keybinds, and System Info are available directly from the main menu. Bar Widgets, Quick Actions, Appearance, and Power Settings replace the menu contents in the same card and provide a Back control. Press Esc or click outside the card to close it from any page.

The Utilities section opens the unified Settings application directly. Phase 1 Settings is a read-only capability overview with section search and keyboard/mouse navigation. It can also be opened with dwm-settings open.

Network Popover

The panel network indicator opens a Quickshell network popover. It shows active NetworkManager connections, scans visible Wi-Fi networks, and connects to open or WPA personal networks directly. Successful Wi-Fi connections are saved as NetworkManager profiles, so they reconnect normally in later sessions.

Hidden SSIDs and enterprise Wi-Fi are handled through the optional nm-connection-editor fallback when it is installed.

Bluetooth Popover

The panel Bluetooth indicator opens a compact device manager. It can power the adapter on or off, scan for devices, pair and trust a new device, connect a paired device, and disconnect a connected device through bluetoothctl.

Panel Widgets

The Bar Widgets page can show or hide the workspace, volume, Bluetooth, network, and power widgets. Those choices are stored in the project-owned ~/.config/lyona/panel-widgets.conf state and apply to every monitor and future Quickshell session. Settings Appearance exposes the same shared controls and can restore the safe all-on default. The redesigned panel retains the active-window title, status segments, and system tray, and shows all nine dwm tags (workspaces). Hovering icon-only panel controls displays a text tooltip.

The panel, popovers, and control-center cards use fully opaque colors. Their palette follows the active theme in themes.toml and updates when that file is changed.

Modules

System Health

System Health opens as a separate full-screen dashboard on the current monitor. It starts two read-only scans: session checks run immediately, and a privileged scan completes current-boot journal, kernel, system-service, and drive checks. If cached or NOPASSWD sudo access is available, the scan runs without a prompt. Otherwise the running polkit agent requests graphical authorization. Cancelling the prompt leaves a partial report and marks its coverage as incomplete.

The dashboard groups checks into:

• Boot and kernel errors from journalctl, with dmesg as a fallback
• Failed user and system services, one service per row
• Memory, pressure, load, swap, filesystem space, and inode use
• Local routing, resolver, and NetworkManager state
• X11, D-Bus, dwm, Quickshell, Picom, audio, and managed configuration
• Required commands, libraries, terminals, and package-database consistency
• Available battery, thermal, and SMART drive-health data

Use Issues Only to hide passing checks. Expand any card to see bounded evidence; the dashboard counts the complete matching log set even when only a sample is displayed. It does not contact an external service to test Internet connectivity and does not scan previous boots.

Boot-journal and kernel-error cards with matching entries include Copy and Export. Copy sends the card’s readable bounded evidence to the X11 clipboard with xclip. Export saves the same content in the user’s home directory as a private timestamped file, such as boot2026-07-09-143000.txt or kernel-errors2026-07-09-143000.txt. Existing files are never overwritten.

Repair buttons always require confirmation. Each failed service row offers Start, Stop, Restart, Disable, and Enable. User units are managed with systemctl --user; system units request administrator authorization through polkit. An action is accepted only while that exact service remains failed. The dashboard can also restart known desktop/audio components, launch the interactive dependency installer, restart NetworkManager or Bluetooth, and repair the detected time-synchronization provider.

Installing the health helper in a root-owned system path remains recommended:

make
sudo make install-system

The managed copy under ~/.local/share/lyona is never elevated itself. If the installed helper is unavailable, cached or NOPASSWD sudo can still run the validated root-owned system commands. Polkit authorization requires the root-owned installed helper.

Quick Actions

Appearance

Power Settings

The Power Settings card retains the existing persisted screen-DPMS and auto-lock controls. Each feature can be enabled or disabled and assigned a 5-minute, 10-minute, 15-minute, 30-minute, or 1-hour timeout.

The full Settings Power page also shows battery, external-power, profile, suspend, and lid capabilities. Its Lock, Log Out, Suspend, Reboot, and Shutdown buttons use the same shared root QML action model and confirmation policy as the panel Power menu. Denied or failed actions remain attributed to the surface that requested them.

Defaults and Startup Applications

Settings -> Defaults manages browser, terminal, file-manager, and selected MIME handlers through versioned XDG records. Restore Previous is offered only while the recovery image still matches the state written by the last action.

The same page lists effective XDG autostart entries and their vendor or user origin. Enable, disable, and reset create or update user overrides for the next login; vendor desktop files are never edited. Changes to the locker, compositor, or polkit agent require explicit confirmation.

Keybind Viewer

Displays all bindings from hotkeys.toml in a searchable Quickshell list. Same as pressing Super + /.

Running from Terminal

dwm-controlcenter

The script is a compatibility wrapper around the Quickshell IPC target:

quickshell ipc --path "${XDG_DATA_HOME:-$HOME/.local/share}/lyona/config/quickshell/shell.qml" call controlcenter toggle

Open or refresh System Health directly through its IPC target:

quickshell ipc --path "${XDG_CONFIG_HOME:-$HOME/.config}/quickshell/shell.qml" call systemhealth open
quickshell ipc --path "${XDG_CONFIG_HOME:-$HOME/.config}/quickshell/shell.qml" call systemhealth refresh

The diagnostic helper can also produce its structured snapshot in a terminal:

dwm-system-health scan-user

Settings

The unified Settings application provides one place to inspect desktop capabilities and see which features are available, restricted, or planned.

Open Control Center with Super+F1, then select Settings from the main menu. You can also run:

dwm-settings open

The Displays section discovers connected outputs and their advertised modes, lets you edit resolution, refresh rate, position, rotation, primary state, and output enablement, and manages named layouts. Choose Apply changes to test the complete layout for 15 seconds, then Keep changes to accept it or Revert to restore the captured layout. Timeout or closing Settings also restores the prior layout. Saved layouts can be reused later; Use at next login installs the selected layout for future X11 sessions after a separate confirmation and administrator authorization. The machine-oriented dwm-settings-display helper exposes discover and watch, complete-layout save and preview, named preview-profile, timed keep, revert, and preview-status, plus authorized install-profile and rollback-system actions. Named layouts live under the lyona XDG config directory. Legacy incomplete layouts remain available to dwm-display-profile, but Settings requires them to be resaved as complete layouts before preview or persistent installation.

The Displays section also sets display scaling. Enter an Xft DPI between 72 and 384, or use the 100%, 125%, 150%, 175%, and 200% presets. Applying writes Xft.dpi to dpi.Xresources in the lyona XDG config directory and merges it into the running X resource database; autostart reapplies it at every login. The pane reports whether the active scale is saved, session-only, or the X server default, and shows the primary output’s measured DPI as a suggestion. Reset removes the saved value and clears Xft.dpi from the running database without disturbing other X resources. Scaling is not a timed preview: only applications started after the change pick up the new value, so restart dwm and the shell to rescale them too. The helper actions are dpi-set, dpi-reset, and the startup-only dpi-apply-saved.

The Input section shows each XInput device by a stable hardware identity and offers only properties its driver exposes. Pointer acceleration, natural scrolling, tap-to-click, keyboard layout, and modifier options are supported when available. Changes use a timed preview with Keep and Revert. Reset is a separate direct action that restores and persists the driver’s default. Kept values are reapplied idempotently at session startup when the device exposes a stable udev or physical sysfs identity. Devices without one remain session-configurable and report that persistence is unavailable. Unsupported per-device properties remain visible with an explanation.

Type to search section names and descriptions. Use Up and Down to move through the filtered sections, Enter to select one, or Escape to close Settings. The Refresh button runs a new bounded capability snapshot; Settings does not add an idle polling timer.

Command-line IPC actions are also available:

dwm-settings open
dwm-settings refresh
dwm-settings status
dwm-settings close

Existing window-rules.toml files are preserved during upgrades. If your file predates Settings, add this entry inside its rules array:

{ title="dwm settings", isfloating=1, alwaysontop=1 },

Saving the file applies the rule through dwm’s normal hot reload. A customized rule with the same title can be retained instead.

The Use at next login display action writes only the managed 90-lyona-display.conf fragment after a separate confirmation and polkit authorization. The installed helper accepts validated display records only, backs up the previous managed next-login fragment, and offers Restore login backup. It does not capture the live XRandR layout. Later phases add connectivity, audio, power, defaults, personalization, and system-management operations.

How lyona Works

lyona uses a maintained fork of dwm, a compact window manager for X11. A window manager controls where application windows appear, how they are arranged, and which window receives input. Unlike a full desktop environment, upstream dwm focuses on this core job and is configured primarily in source code.

The dwm community traditionally distributes optional features as source-code “patches.” lyona already integrates and maintains a curated set of those ideas alongside its own runtime configuration, Quickshell desktop layer, Settings experience, and system helpers. Users do not need to find or apply patches themselves.

This page documents the major technical additions to the window-manager core and how they support the complete desktop experience.

Window Management Patches

Pertag

Each tag independently remembers its layout, master count, and master/stack sizing. Switching tags restores the previous layout for that tag.

Cfact

Assign per-window size weights within the stack area. Windows are no longer forced to equal height.

Movestack

Reorder windows within the stack without using the mouse.

Window Swallowing

When a GUI application is launched from a terminal, it replaces the terminal in the layout. Closing the app brings the terminal back.

Controlled via window rules in config.h:

{ "Alacritty", NULL, NULL, 0, 0, 1, 0, -1 },  /* isterminal = 1 */

Fullscreen (3-State)

Three fullscreen modes available:

Bar & EWMH

Quickshell Integration

The managed Quickshell layer reads dwm workspace and active-window state through EWMH-compatible helpers so the panel stays synchronized with X11 state. The Control Center includes a Power page for screen DPMS and automatic locking settings backed by ${XDG_CONFIG_HOME:-$HOME/.config}/lyona/power.conf.

EWMH Compliance

Implements _NET_WM_STATE, _NET_CURRENT_DESKTOP, _NET_NUMBER_OF_DESKTOPS, and related atoms so external tools and taskbars work correctly.

Window Icons

Title bar icons via _NET_WM_ICON. Applications that set this atom display their icon in the bar.

Systray

A built-in system tray is compiled in and can be configured in config.h.

Visual

Noborder

When only one window is visible on a tag, its border is automatically removed for a cleaner look. Borders return when a second window appears.

Cursor Warp

When focus moves to a different window or monitor (via keyboard), the mouse cursor warps to the center of the newly focused window.

Live Configuration

TOML Hotkeys (hotkeys.toml)

Keybindings are parsed from config/hotkeys.toml at runtime. Edit and save — bindings update without recompiling or restarting dwm.

TOML Themes (themes.toml)

Colors for dwm, terminal, GTK, and Qt are sourced from config/themes.toml. Save the file to apply a new theme instantly across supported apps.

Scripts & Utilities

Multi-Monitor

Xinerama support keeps tags independent per monitor. Windows can be moved between monitors with Super + Shift + ,/..

Troubleshooting

Gear Lever does not open

Gear Lever requires Flatpak’s document portal. If launching it prints a bwrap: Can't find source path /run/user/.../doc/by-app/... error, the portal process has outlived its FUSE mount. Repair the current user session with:

systemctl --user restart xdg-document-portal.service
flatpak run it.mijorus.gearlever

The recommended and full installers include Flatpak, the GTK portal, and a user-scoped Gear Lever installation from Flathub by default. To repair only the application setup from an installed lyona checkout, run:

install-gearlever

Run the dependency checker first — it covers most common issues:

dwm-diagnostics

Or use the Control Center → System Health.

dwm Won’t Start

Black screen / returns immediately to login:

• Run dwm-diagnostics and resolve any required X11/session failures.
• Preview required packages with ./install.sh --dry-run --profile core.
• Check .xinitrc exists and ends with exec dwm
• Run startx from a TTY to see error output in the terminal

dwm: cannot open display:

• You must launch dwm from a TTY, not an existing X session
• If using a display manager, ensure dwm.desktop is in /usr/share/xsessions/

No Status Bar / Quickshell Missing

• Install the recommended desktop layer: ./install.sh --profile recommended
• Verify the managed config exists: ls ~/.config/quickshell/shell.qml
• Run manually: quickshell --no-duplicate
• Check fonts: fc-list | grep -i meslo

Terminal Won’t Open (Super+X)

• Run alacritty from an existing shell to inspect its error directly
• Install Alacritty with sudo pacman -S alacritty
• Confirm the fixed terminal in config/hotkeys.toml:

  [vars]
  terminal = "alacritty"
  

Herdr is an optional terminal workspace, not a graphical terminal emulator. Install it explicitly and use DWM_HERDR=1 dwm-terminal to run it inside Alacritty. The default Super+X binding remains plain Alacritty.

Browser Won’t Open (Super+B)

• Run dwm-default-apps status to inspect the current default browser
• Run dwm-default-apps browsers to list installed browser desktop files
• Set one with dwm-default-apps set-browser firefox.desktop
• Open Settings -> Defaults to inspect provider details, candidates, and the Restore Previous action
• Ensure xdg-utils is installed so xdg-settings, xdg-mime, and xdg-open are available

Startup Application Change Failed

• Open Settings -> Defaults and inspect the entry origin, effective state, and detail. Malformed or conditional vendor entries are intentionally not rewritten.
• Changes apply at the next login; Settings does not start or stop the application in the current session.
• A stale-revision error means the entry changed after it was displayed. Use Refresh and retry.
• Reset to vendor removes only the managed user override. Existing vendor desktop files are never edited.

Themes Not Applying

• Confirm themes.toml is at ~/.config/lyona/themes.toml
• Check the [active] section has a valid theme name
• Manually trigger: kill -USR1 $(pidof dwm)
• Run theme-apply.sh directly to see any errors

Keybinds Not Working

• Check config/hotkeys.toml for syntax errors — invalid TOML silently fails
• Verify the key name is correct (use xev to find X11 key names)
• If a bind still doesn’t work, add it as a fallback in config.h and recompile

Multi-Monitor Issues

• Tags not syncing across monitors: run dwm-diagnostics
• Cursor doesn’t follow focus: verify cursor warp is enabled in config.h (cursorwarp = 1)
• Persistent resolution or positioning: run dwm-display-setup detect, then dwm-display-setup. The wizard previews changes before writing Xorg config.
• Bad persistent layout: run dwm-display-setup rollback, then log out and back in. From a TTY, remove /etc/X11/xorg.conf.d/90-lyona-display.conf if Xorg cannot start.
• TearFree is enabled only when the active Xorg driver exposes a compatible option or RandR property. Unsupported drivers are left unchanged.
• NVIDIA Full Composition Pipeline is enabled in generated persistence only when the relevant output uses the NVIDIA kernel driver and an NVIDIA Xorg provider is available, including supported hybrid configurations. Run dwm-display-setup capabilities to inspect the detected fallback before saving a layout.
• Display layout profiles: run dwm-display-profile dir and dwm-display-profile template to create optional xrandr profiles

NVIDIA / Suspend Issues

• Black screen on wake: run scripts/nvidia-suspend-test.sh to diagnose
• DPMS/screensaver issues: use Control Center -> Power, or run scripts/disable-powersaving to disable blanking and DPMS for the current session

Picom / Compositor Artifacts

Restart picom via the Control Center (Quick Actions → Restart Picom) or:

pkill picom; setsid -f picom --backend xrender

If artifacts persist, set a different backend in ~/.config/picom.conf or run with PICOM_BACKEND=glx or PICOM_BACKEND=egl.

Still Stuck?

• Open an issue: github.com/technicks89/dwm-titus/issues
• Run the full check: bash scripts/check-deps.sh