Moonarch

Reproducible Arch Linux desktop environment — fully automated from bare metal to a configured Niri (scrollable tiling Wayland) system with Catppuccin Mocha theming.

Moonarch combines archinstall for the base system with post-install automation that handles packages, XDG defaults, system services, greeter, idle management, and a Walker launcher with native providers and dmenu-based helper scripts. The result is a complete development/productivity desktop that can be rebuilt from scratch in minutes.

Why These Choices

Component	Choice	Why
Compositor	Niri	Scrollable tiling — no fixed grid, infinite horizontal workspace. Purpose-built Wayland compositor, not an X11 port.
Greeter	greetd + moongreet	Minimal, Wayland-native login. moongreet provides GTK4 UI with fingerprint support, running inside its own Niri instance.
Lock Screen	moonlock	ext-session-lock-v1 protocol — compositor guarantees lock on crash. PAM + fprintd, GPU blur, multi-monitor.
Power Menu	moonset	GTK4 Layer Shell overlay above Waybar. Lock, logout, hibernate, reboot, shutdown with confirmation.
Idle Manager	stasis + wayland-pipewire-idle-inhibit	Separate AC/battery power plans. Brightness dimming, DPMS, lock (via moonlock), and suspend on configurable timeouts. The companion inhibitor holds a Wayland idle-inhibitor while audio plays — keeps the screen awake during windowed browser video, which stasis' pactl detection skips by design.
Bar	Waybar	Wayland-native, highly customizable. Niri workspace/window modules via community plugins.
Launcher	Walker + Elephant	Wayland-native GTK4 launcher with built-in providers for apps, clipboard, bluetooth, audio, files, and calculator. Dmenu mode for custom scripts (VPN, CPU governor).
Terminal	Foot	Fast, minimal Wayland-native terminal. Server mode for instant window spawning.
Shell	Zsh	Programmable completion, FZF integration, syntax highlighting.
Audio	PipeWire	Drop-in replacement for PulseAudio/JACK with lower latency. RNNoise input denoising configured out of the box.
Display Management	kanshi + wdisplays-persistent	kanshi auto-switches output profiles on hotplug. wdisplays-persistent saves changes directly to kanshi config.
Notifications	swaync	GTK4 notification daemon with DND toggle, grouping, MPRIS support. Fractional scaling via native GTK4.
Clipboard	cliphist + Walker	Clipboard history stored in runtime dir, wiped on session start. Walker provides the picker UI.
GTK Theme	Colloid-Grey-Dark-Catppuccin	Catppuccin Mocha palette, grey accent, explicit dark variant.
Icons	Colloid-Grey-Catppuccin-Dark	Catppuccin-colored icon set matching the GTK theme.
Cursor	Sweet-cursors	Visible on dark backgrounds without clashing.
Font	UbuntuSans Nerd Font	Clean sans-serif with full Nerd Font glyph coverage for bar/terminal icons.
Wallpaper	waypaper + awww	waypaper provides GUI selection, awww handles animated transitions (60 FPS, 2s crossfade).
Night Light	wlsunset	Wayland-native blue light filter via wlr-gamma-control. Toggleable from Waybar brightness group.
Firewall	UFW	Simple deny-incoming/allow-outgoing default. Sane baseline without iptables complexity.
AUR Helper	paru	Rust-based, pacman-compatible. Supports custom PKGBUILD repos for moongreet/moonlock/moonset.

Quick Start

Fresh Install (Bare Metal)

1. Boot the Arch ISO and download the config:

   curl -O https://gitea.moonarch.de/nevaforget/moonarch/raw/branch/main/config/user_configuration.json
   archinstall --config user_configuration.json
   

2. Choose disk and kernel interactively — everything else comes from the config.
3. Reboot, log in, then:

   /opt/moonarch/scripts/post-install.sh
   

4. Reboot again — done.

The archinstall config clones this repo to /opt/moonarch via custom-commands. post-install.sh handles the remaining ~95 packages, all configs, themes, services, and user setup.

Update

moonup   # or: moonarch-update

Interactive updater that upgrades system and AUR packages, reconciles package lists against what's installed, and cleans orphaned packages. Config deployment happens automatically via the moonarch-git package on paru -Syu.

Health Check

moondoc   # or: moonarch-doctor

Diagnostic tool that verifies the system state against moonarch defaults: services, configs, packages, helper scripts, firewall, shell and directory permissions. Reports pass/fail/warn per check with a summary at the end.

Project Structure

config/
  user_configuration.json       archinstall config (locale, audio, services, custom-commands)

packages/
  official.txt                  Arch repo packages (~80), one per line
  aur.txt                       AUR packages (~20), one per line

scripts/
  lib.sh                        Shared helpers sourced by post-install.sh
  post-install.sh               Main automation (packages, configs, themes, services)
  moonarch-update               Interactive updater (deployed to /usr/bin/ as moonup)
  moonarch-doctor               System health checker (deployed to /usr/bin/ as moondoc)

defaults/
  xdg/                          System-wide XDG configs (deployed to /etc/xdg/)
    niri/config.kdl               Compositor: layout, keybinds, startup apps
    waybar/config, style.css      Bar: modules, layout, Catppuccin styling
    walker/config.toml, themes/   Launcher: Walker config + moonarch theme (Catppuccin Mocha)
    foot/foot.ini                 Terminal: font, colors, keybinds
    swaync/config.json, style.css Notifications: appearance, behavior, MPRIS
    kanshi/config                 Display profiles (empty seed, user-configured via wdisplays)
    stasis/stasis.rune            Idle manager: AC/battery power plans
    pipewire/                     Audio: RNNoise input denoising
    waypaper/config.ini           Wallpaper manager: backend, folder, transitions
    fastfetch/config.jsonc        System info display
    gtk-3.0/, gtk-4.0/           GTK theme settings

  bin/                          Helper scripts (deployed to /usr/bin/)
    moonarch-sink-switcher        Audio output switcher (walker dmenu + pactl)
    moonarch-vpn                  VPN connection manager (walker dmenu + nmcli)
    moonarch-cpugov               CPU governor switcher (walker dmenu + auto-cpufreq)
    moonarch-btnote               Bluetooth device battery monitor (upower + notify-send)
    moonarch-capsnote             Caps Lock toggle notification
    moonarch-waybar-cpugov        Waybar module: CPU governor status
    moonarch-waybar-gpustat       Waybar module: GPU utilization
    moonarch-waybar-hidpp         Waybar module: Logitech HID++ device battery
    moonarch-waybar-batsaver      Waybar module: battery conservation mode indicator
    moonarch-waybar-updates       Waybar module: package update checker (repo + AUR)
    moonarch-batsaver-toggle      Toggle battery charge limit (80% ↔ 100%)
    moonarch-nightlight           Toggle wlsunset blue light filter on/off
    moonarch-waybar-nightlight    Waybar module: nightlight status

  shell/zshrc                   Zsh config: prompt, aliases, FZF, completion
  etc/greetd/                   greetd daemon + greeter Niri config
  etc/moongreet/                moongreet configuration
  etc/systemd/user/             Systemd user services (cliphist, kanshi, walker, nautilus)
  etc/systemd/system/           System service (battery conservation restore on boot)
  etc/udev/rules.d/             udev rules (battery threshold permissions)
  backgrounds/wallpaper.jpg     Default wallpaper (shared by desktop, greeter, lock screen)

Startup Sequence

greetd ─► niri (greeter instance) ─► moongreet ─► user authenticates
                                                         │
                                                         ▼
                                                   niri (user session)
                                                         │
                           ┌──────────┬────────┬────────┬──────────┐
                           ▼          ▼        ▼        ▼          ▼
                        waybar     swaync   foot     waypaper   nm-applet  wlsunset
                        (bar)    (notify) (server)  (wallpaper)  (VPN)    (nightlight)

                        systemd user services (graphical-session.target):
                        kanshi, cliphist, walker, nautilus

Keybinds (Default)

Key	Action
Super+Return	Open terminal (foot)
Super+Space	App launcher (walker)
Super+Q	Close window
Super+O / Super+Tab	Overview
Super+F	Maximize column
Super+Shift+F	Fullscreen window
Super+V	Toggle floating
Super+H/J/K/L	Focus left/down/up/right
Super+Ctrl+H/J/K/L	Move window
Super+Shift+H/J/K/L	Focus monitor
Super+1-9	Switch workspace
Super+C	Clipboard history
Super+E	File manager
Super+A	Audio control (walker)
Super+N	VPN manager
Mod+Escape	Session menu (moonset)
Print	Screenshot
Ctrl+Print	Screenshot screen
Alt+Print	Screenshot window

Customization

All system configs live in /etc/xdg/ and can be overridden per-user in ~/.config/:

Component	System Default	User Override
Niri	/etc/xdg/niri/config.kdl	~/.config/niri/config.kdl (includes system config)
Waybar	/etc/xdg/waybar/	~/.config/waybar/
Walker	/etc/xdg/walker/	~/.config/walker/
Foot	/etc/xdg/foot/foot.ini	~/.config/foot/foot.ini
swaync	/etc/xdg/swaync/	~/.config/swaync/
kanshi	/etc/xdg/kanshi/config	~/.config/kanshi/config
PipeWire	/etc/xdg/pipewire/	~/.config/pipewire/
Zsh	/etc/zsh/zshrc.moonarch	~/.zshrc + ~/.zshrc.d/

Helper scripts in /usr/bin/moonarch-* are not meant to be overridden — they are part of the system and updated via paru -Syu.

System Services

Service	Purpose
greetd	Login greeter (runs moongreet inside Niri)
NetworkManager	Network management (WiFi, VPN, Ethernet)
bluetooth	Bluetooth stack (bluez)
systemd-timesyncd	NTP time synchronization
ufw	Firewall (deny incoming, allow outgoing)
auto-cpufreq	CPU frequency scaling (AC: performance, battery: powersave)

User Services (systemd --user)

Service	Purpose
cliphist	Clipboard history (wipes on session start, stores in runtime dir)
kanshi	Dynamic display configuration (auto-switch output profiles on hotplug)
nautilus	File manager preload (faster first launch)
stasis	Idle manager (dimming, DPMS, lock, suspend on AC/battery plans)
wayland-pipewire-idle-inhibit	Holds a Wayland idle-inhibitor while audio plays (keeps screen awake for windowed browser video that stasis skips)
walker	Walker application launcher (GTK4 service mode for instant startup)

Moonarch Ecosystem

Moonarch is the deployment and configuration layer. Three companion projects provide the Wayland session UI — all built with Rust + gtk4-rs and sharing Catppuccin Mocha theming:

Project	Role	Installed via
moongreet	greetd greeter (GTK4 Layer Shell, fingerprint, i18n)	paru -S moongreet-git
moonlock	Wayland lock screen (ext-session-lock-v1, PAM, fprintd)	paru -S moonlock-git
moonset	Power menu overlay (GTK4 Layer Shell)	paru -S moonset-git

These are built from a custom paru package repository added during post-install.

License

MIT