👑 Nomarchy

Nomarchy is a professional-grade NixOS distribution that ships a highly curated Hyprland desktop on a strictly declarative, flake-based foundation. It provides a highly polished, "it just works" experience for power users who want a beautiful Wayland environment without sacrificing the reliability of NixOS.

✨ Key Features

• Purely Declarative: Your entire desktop—themes, fonts, wallpapers, and toolchains—is defined in code.
• Modular Merging Architecture: Distro code and user code are strictly separated. You can update the distro core without ever touching or breaking your personal configurations.
• Interactive "Smart" Installer: Detects hardware, sets up networking, localizes timezones/keymaps, and offers multi-select software profiles.
• Erase Your Darlings (Optional): Optional BTRFS root-wipe on boot ensures your system stays pristine and 100% declarative.
• Dynamic Theming Engine: 20+ built-in themes with instant UI feedback via IPC (swww, waybar, and stylix).
• Portable State (nomarchy-sync): Easily backup and sync your declarative config and dynamic state (theme/wallpaper choices) to a private Git repo.

---

📂 Component-Based Architecture

Nomarchy uses a Feature-Centric Directory Structure. For a comprehensive breakdown of the system architecture, folder roles, and module logic, see the Detailed Architecture Documentation.

Configuration, modules, and utilities are strictly organized to maintain sanity as the system grows.

• core/: Foundational OS & User defaults (Bootloader, Audio, Bluetooth, core system features).
• features/: Isolated modules containing Nix logic and raw dotfiles.
  • features/apps/: App-specific configs (e.g., features/apps/btop/, features/apps/kitty/), each containing their own default.nix and standalone config/ directory mapped via Home Manager.
  • features/desktop/: Desktop environment components (e.g., Hyprland, Waybar).
  • features/scripts/utils/: Consolidated repository for all custom Nomarchy bash scripts, centrally packaged and injected into the user's PATH with correct dependencies.
• themes/: The global theming engine. It holds pure color data and logic. Theme-specific app layouts (like a custom Waybar layout) are stored directly inside the app's feature folder, solving the matrix problem of theming.

---

📥 Installation

1. Try it in a VM (Recommended)

Verify the experience without touching your hardware:

./bin/utils/nomarchy-test-installer

This builds a full graphical VM of the installer environment. Once inside, click the Install Nomarchy icon or run nomarchy-install.

2. Build the Installer ISO

To install on physical hardware, generate your own bootable image:

./features/scripts/utils/nomarchy-build-iso       # Minimal TTY installer
./features/scripts/utils/nomarchy-build-live-iso  # Graphical try-before-install

The ISO will be located at ./result/iso/nixos-*.iso. Flash it to a USB drive and boot.

3. Run the Installer

Once booted into the Live environment, launch the installer:

nomarchy-install

The wizard will guide you through:

• Networking: An interactive wizard to connect to Wi-Fi if needed.
• Hardware: Optimized profiles for Dell XPS, Framework, Apple T2, and more.
• Storage: Choice between Standard Ext4 or Encrypted BTRFS with optional Impermanence.
• Localization: Searchable timezones and keyboard layout selection.

Already on NixOS?

Layer Nomarchy onto an existing 25.11 install without reformatting — see the Migration Guide.

---

🛠️ Configuration & Usage

Nomarchy uses a "Downstream" model. After installation, your configuration lives in /etc/nixos/ and is split into three main parts:

1. Distro Core (Upstream)

Managed via the public Git repository. This is the engine. You should generally not modify files here.

2. Your System (system.nix)

Add system-wide packages, services, and hardware tweaks here. Example: Adding a persistent directory for Docker if using Impermanence:

environment.persistence."/persist" = {
  directories = [ "/var/lib/docker" ];
};

3. Your User Environment (home.nix)

Add user-level packages, aliases, and dotfiles here. Example: Overriding the default terminal:

nomarchy.home.terminal = "kitty";

For the full list of nomarchy.* options you can set in system.nix and home.nix, see the Options Reference. Hit a rebuild error? Check Troubleshooting. For where the project is heading next, see the Roadmap.

Applying Changes

After editing your files, apply them instantly. IMPORTANT: Nomarchy requires the --impure flag for evaluation. You MUST use the following aliases rather than standard NixOS commands:

sys-update  # Rebuilds the NixOS system (Runs: sudo nixos-rebuild switch --flake .#default --impure)
env-update  # Reloads your Home Manager environment (Runs: home-manager switch --flake .#default --impure)

---

🚀 Commands & Keybindings

The full list lives in docs/KEYBINDINGS.md (auto-generated from the Hyprland configs). A few highlights:

Keybinding	Action
Super + Space	App Launcher (Walker)
Super + Shift + Space	Nomarchy Menu (Walker)
Super + Alt + Space	Toggle Top Bar (Waybar)
Super + Return	Open Terminal
Super + Q	Close Window

Utility Scripts

Nomarchy includes dozens of productivity scripts available in your PATH. Some highlights:

• nomarchy-sync push <repo>: Backup your setup to Git.
• nomarchy-theme-bg-next: Cycle to the next wallpaper in the current theme.
• nomarchy-menu: The central hub for all utilities and pickers.

---

Built with ❤️ using NixOS, Hyprland, Stylix, and the Nomarchy Community.