From reading
to running.

Start one experiment.

From the repository root on the host where the lab VMs were prepared, run:

python3 vm/launch.py lucent

This starts the existing guest and opens its console. The guests appear in Virtual Machine Manager under QEMU/KVM User session. The launcher expects the local VM inventory and disks; cloning the repository alone does not create a ready-to-boot VM.

Lucid and Noctalia are separate guests. Shut down the current guest before opening the next:

python3 vm/lab.py shutdown lucent
python3 vm/launch.py lucid
# Later, switch to the C++ comparison:
python3 vm/lab.py shutdown lucid
python3 vm/launch.py noctalia

Starting from scratch? Follow the repository’s OS installation and VM preparation guide. Disk selection and any destructive OS installation steps remain manual.

Take the desktop for a spin.

A useful first five minutes

1. Launch a terminal. Press Super + Space, search for Foot, and press Enter. It opens a real application window.
2. Try the tiling. Open another terminal. Hyprland manages ordinary windows with the existing Omarchy bindings. Lucent’s widgets stay outside that tiling layout.
3. Move a widget. Drag the calendar’s background and release. Restart Lucent and the position should return.
4. Change the background. Open the wallpaper carousel, select with the arrows and press Enter. Lucent persists the choice and paints its native background surface.
5. Explore the selectors. Toggle widgets, reset their positions, or select the light/dark palette in the launcher header.

The seven available widgets are calendar, clock, weather, media, system monitor, notes and focus timer. Notes currently support one line. The timer supports start, pause and reset; its running state is not persisted across restart.

Control it from a terminal

lucent-cli launcher toggle
lucent-cli wallpapers open
lucent-cli widgets open
lucent-cli inspect
lucent-cli quit

inspect includes geometry and frame counters, as well as the current query and note. Review that personal content before sharing output. quit stops Lucent; explicit integration rollback restores stock UI.

The pieces fit at their boundaries.

cargo run --manifest-path lucent/Cargo.toml --locked --release -p hello-layer

Build the native client.

The tested baseline is Omarchy 4.0.4 with Hyprland 0.56.2 and Lua configuration. These integration scripts target Omarchy; they are not a generic installer for an arbitrary Linux session.

Arch build/runtime packages: rust, pkgconf, wayland, libxkbcommon, fontconfig, pam, polkit, swayidle, hyprlock, wl-clipboard, wtype, clang, vulkan-icd-loader and a suitable Vulkan driver. Desktop adapters use native MPRIS D-Bus for media, the PulseAudio protocol for audio, networkmanager and bounded curl for weather/artwork. Headless distribution shortcuts may still use playerctl or wpctl.

cargo build --manifest-path lucent/Cargo.toml --locked --release --workspace
python3 scripts/lucent-setup.py install
systemctl --user start lucent.service

Check the running client first. Then enable its managed startup and shortcut blocks:

python3 scripts/lucent-setup.py activate

Installation is per-user. Activation edits marked blocks in user bindings.lua and autostart.lua. Packaged files under /usr/share/omarchy are untouched. Activation stops the exact installed stock shell while unlocked. Native services own its visible responsibilities; explicit rollback restores stock startup and notification ownership.

Predictable state, real services.

Layout and preferences

~/.local/state/lucent/desktop.json stores versioned widget positions, visibility, pinned apps, notes and palette choice. Saves are atomic. Unsupported versions are left intact and saving is disabled until corrected.

Wallpapers

Place images in ~/Pictures/Wallpapers or ~/.config/lucent/wallpapers. Lucent snapshots and decodes a selection before committing it. The native browser also searches Wallhaven and Alpha Coders. Wallpaper only retains your colors; Wallpaper + colors extracts a semantic palette. Named palettes and current-wallpaper color extraction are available in Themes. Omarchy does not choose Lucent’s palette.

Weather

The Weather and location command opens manual coordinates, Celsius/Fahrenheit, current conditions and a three-day forecast. Preferences use normal desktop settings; the optional ~/.config/lucent/weather.json is imported only while those preferences are absent. Enabled locations refresh from Open-Meteo every 15 minutes and retain their last successful result on failure. There is no IP lookup. Keep personal location files outside Git. This Weather slice awaits its Rust, visual and native acceptance checks.

External integrations

Hyprland changes arrive through its event socket. Clock and system samples run at 1 and 5 seconds respectively. Audio, networking, Bluetooth, power and media use native observations. Only relevant changes invalidate surfaces. Click the media capsule for player selection and targeted playback controls; visible playing progress advances locally from its last native sample.

Application execution

XDG desktop entries are parsed into executable and argument arrays, with supported field codes handled explicitly. Commands are not evaluated through a shell.

Local IPC

A mode-0600 socket lives at $XDG_RUNTIME_DIR/lucent.sock. Commands use an allowlist; a file lock prevents duplicate clients.

Lock, notifications, login.

The bar’s bell opens Lucent’s notification history. The lock button and Super+Ctrl+L request its native secure locker. Wayland enforces the lock; the existing Omarchy PAM policy verifies your password. The login greeter is another client of the same component API and Vulkan renderer, with greetd managing authentication and session startup.

sudo pacman -S --needed greetd
sudo python3 scripts/lucent-login.py install
sudo python3 scripts/lucent-login.py test
# After checking VT9, stop the test:
sudo systemctl stop lucent-greeter-test
sudo python3 scripts/lucent-login.py activate

Activation preserves the current desktop. To restore the previous display manager for next boot, run sudo python3 scripts/lucent-login.py rollback. The installer records its original selection and greetd configuration.

A way back is part of the design.

Lucent

python3 scripts/lucent-setup.py rollback

Rollback stops Lucent, removes the managed blocks and restores stock shortcuts and bar visibility. Installed binaries, widget settings and the selected wallpaper remain. For the prepared VM’s original wallpaper:

omarchy-theme-bg-set "$(cat ~/.config/lucent/original-wallpaper)"

Lucid or Noctalia

~/desktop-lab/scripts/rollback.sh

Log out and back in afterward. The original user configuration is restored; packages remain installed and their before/after inventories remain available for review.

The same backdrop.

Lock and login screens paint the desktop wallpaper through the native renderer. Centered cover fitting fills each display without stretching. The locker reads the current background at launch; the login screen reads a copy that follows wallpaper changes. The greeter can read that copy while your home stays private.

Run the checks.

cargo fmt --manifest-path lucent/Cargo.toml --all --check
cargo clippy --manifest-path lucent/Cargo.toml --locked --workspace --all-targets -- -D warnings
cargo test --manifest-path lucent/Cargo.toml --locked --workspace
python3 -m unittest discover -s tests -v

The VM harness sends real QEMU pointer and keyboard events. Run it from the prepared host with the Lucent guest unlocked at 1920 × 1080:

python3 vm/test-framework.py
python3 vm/test-launcher.py
python3 vm/test-visual.py
python3 vm/test-runtime.py
python3 vm/measure-framework.py
python3 vm/measure-framework.py --seconds 120 --profile

The input harness preserves the original widget settings and wallpaper. The measurement tool temporarily sets the stay-awake marker consumed by Lucent’s headless idle adapter, then restores its prior state even when a measurement fails. CPU, memory and display metadata come from the guest.

The optional profile run temporarily enables per-frame CPU timings through a private runtime service override, then removes it and restarts the original configuration even on failure. Reports distinguish preparation, text rasterization, texture uploads and driver calls. Linux RSS/PSS snapshots and known image/buffer payloads have separate scopes; none is a complete GPU allocation measurement.

Validation combines Rust behavior tests, Python configuration/token/architecture checks, native Vulkan visual comparisons and actual VM interactions. Resource tests separately verify that active textures survive redraws on other surfaces. The full validation report separates executed checks from untested hardware paths. Download the recorded performance JSON.

Built with a clear lineage.

• Omarchy ↗The Arch / Hyprland foundation and retained session tools.
• Lucid ↗Primary visual and interaction reference. The inspected upstream revision is pinned in the lab manifest.
• Noctalia v5 ↗The native C++ comparison, configured through its supported schema.
• Amane ↗Architectural research into immediate-mode native desktop shells.
• Suzuha ↗Reference client studied alongside Amane.
• Architecture decisions ↗Why this project uses an independent framework and client.
• Pinned sources ↗Inspected revisions and archive checksums.

Screenshots are actual captures from the lab. Wallpapers retain their original rights and are shown as part of those desktop captures. The site reuses the client’s Lucent Sans and Lucent Display fonts, derived from Google Sans Flex under the SIL Open Font License. See the repository’s asset attribution.

This explanatory site is built with Astro and small browser scripts. The desktop it documents is a native Rust application.