👑 Nomarchy

Nomarchy is a professional-grade NixOS distribution that replicates the Omarchy Wayland workflow with a strictly declarative, flake-based architecture. It provides a highly polished, "it just works" experience for power users who want a beautiful Hyprland 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:

nix build .#nixosConfigurations.installerIso.config.system.build.isoImage

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. 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 spirit of Omarchy.