Omarchy on NixOS

This project ports the Omarchy desktop and its workflows to NixOS. Nix supplies the operating system, applications, services, and runtime assets. The flake pins upstream Omarchy, Nixpkgs, and Home Manager; a sibling upstream checkout is not required.

The port is experimental. It includes declarative desktop applications and settings, guided installation, first-boot owner provisioning, encrypted-root handoff, and factory reset. Complete installed-system lifecycle testing, physical hardware acceptance, and upstream feature parity remain unfinished.

Use with an existing NixOS configuration

Add this project as a flake input and import its NixOS module:

{
  inputs.omarchy-nix.url = "path:/absolute/path/to/nix_port";
  inputs.nixpkgs.follows = "omarchy-nix/nixpkgs";

  outputs = { nixpkgs, omarchy-nix, ... }: {
    nixosConfigurations.workstation = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        omarchy-nix.nixosModules.default
        ./configuration.nix
        {
          services.omarchy = {
            enable = true;
            users = [ "your-user" ];
            theme = "tokyo-night";
            flake = "/etc/nixos#workstation";
          };
          nixpkgs.config.allowUnfree = true;
          home-manager.users.your-user.home.stateVersion = "26.05";
        }
      ];
    };
  };
}

Keep your existing hardware configuration, filesystems, bootloader, credentials, and state versions. services.omarchy.users names existing accounts; it does not create them. The default application collection includes unfree packages and requires an explicit unfree policy.

The module imports Home Manager integration. Personal desktop options live under programs.omarchy; see modules/home.nix. The standalone Home Manager module is also exported as homeManagerModules.default.

Declare keyboard layout with standard NixOS options:

services.xserver.xkb = {
  layout = "fr";
  variant = "bepo";
};
console.useXkbConfig = true;

Optional system features are declared in the host configuration:

services.omarchy = {
  development.enable = true; # Docker
  development.sudolessDocker.enable = false;
  gaming.enable = true;      # Steam and 32-bit graphics
  gaming.xboxControllers.enable = true;
  fingerprint.enable = true;
  boot.enable = true;        # Plymouth; retains the chosen bootloader
  tailscale.enable = true;
  nordvpn.enable = true;
  onepassword.enable = true;
  ollama.enable = true;      # Does not download models
  ssh.enable = true;
  ssh.openFirewall = true;
  sunshine.enable = true;
  sunshine.openFirewall = false;
};

These examples enable optional features; choose only those appropriate for your host. See modules/nixos.nix and the other modules for option descriptions and defaults.

Personal desktop configuration

New installations seed a public Git repository at ~/.config/omarchy/config. It contains a pinned flake, home.nix, desktop sources under desktop/, and omarchy-desktop.json. Personal applications, themes, wallpaper, fonts, default applications, and keybindings belong to Home Manager. Boot, storage, drivers, accounts, and system services belong to NixOS.

Agents should read that repository's AGENTS.md and the installed omarchy skill before changing settings. Home Manager publishes Nix-adapted skills for supported agents, including Codex and Claude. Requested changes belong in tracked sources, not hand-edited live files or Nix-store targets; Apply & Save deploys and commits successful personal changes. New application configurations need explicit Home Manager deployment in home.nix, not just a file in desktop/. The generated guide is maintained in runtime/config-AGENTS.md; port development instructions live in AGENTS.md. Existing repositories are not overwritten to install new instructions; use the installed skill and deliberately copy/review the guide if needed.

Desktop controls stage declaration changes. Choose Desktop → Apply & Save or run omarchy-desktop-apply to review, build, activate, and commit personal changes locally. omarchy-desktop-status shows pending changes. Personal apply requires no sudo and does not update locks or push commits. Restart applications or log out and back in when they do not reload their configuration.

Use Install → Apps (search Nixpkgs) or omarchy pkg install to search the selected pinned Nixpkgs input. Filter results and use Tab to select multiple packages. Custom-overlay packages are available through omarchy pkg add <attribute>. omarchy pkg remove selects personal packages; it cannot remove bundled system applications.

Apply & Save includes all pending personal edits shown in the review. Cancellation and build failures leave declarations pending. Activation can fail partially; inspect Home Manager conflict backups and the active desktop before retrying. Pending system or port-source edits must be handled separately through NixOS.

Configuration and selected wallpaper assets enter Git and the public Nix store. Keep credentials and private application data outside this repository. Wallpapers must be public images or videos of at most 32 MiB.

The system bootstraps Home Manager until the first successful standalone apply. Later system rebuilds leave the personal profile alone. /etc/nixos remains the privileged system configuration; it is not automatically synchronized with the personal repository. Existing integrated installations require deliberate migration to the standalone layout.

Experimental installation media

Prerequisites and VM setup

Build commands require Nix with nix-command and flakes enabled. The live ISO and guided installer target x86_64 machines; other flake package outputs do not imply a tested ARM installer. Keep network access available: pinned sources on the ISO alone do not guarantee every installed package is cached.

The target must be a writable, unused whole disk with a stable serial number or WWN. Both storage modes refuse disks without that identity or with mounted/in-use partitions. Inspect the live session with lsblk -d -o PATH,SIZE,MODEL,SERIAL,WWN before choosing a disk; names such as /dev/vda alone are not stable identity.

For a disposable virt-manager VM, configure these before starting the ISO:

1. Allocate a disk meeting the selected storage mode's size requirement below; a fresh 64 GiB disk is suitable for erase-mode testing.
2. Choose UEFI/OVMF firmware if installing in UEFI mode; the live ISO must itself boot in UEFI mode. If firmware cannot be changed on the existing VM, create a new VM with the desired firmware before installation. Secure Boot is not configured by this port; use firmware with Secure Boot disabled.
3. Give the virtual hard disk a unique, persistent serial, for example OMARCHY_VM_001. Use the disk's serial field if available, or add <serial>OMARCHY_VM_001</serial> inside that disk's <disk> element in the VM XML, not a serial-console device. Keep virtio disk serials at most 20 characters. See the libvirt disk and firmware XML reference.
4. Attach the ISO as a CD-ROM and boot it. In the live session, test -d /sys/firmware/efi && echo UEFI || echo BIOS identifies the actual firmware boot mode; verify the disk serial with lsblk too.

Do not switch between BIOS and UEFI after installing and expect the existing bootloader to work. After the installer completes successfully, shut down, eject the ISO and boot the installed hard disk with the same firmware. If the VM says "no bootable device," verify the installed disk is attached and in the boot order, firmware matches the installation, and the installer actually completed; do not rerun disk erasure as a troubleshooting step.

Build and install

Build the live image:

nix build path:.#omarchy-iso --out-link result-iso

The image is under result-iso/iso/. Local Nix result links are ignored by version control and retain their outputs against garbage collection. Rebuild and replace the media to obtain source changes.

The live desktop's Install Omarchy on NixOS launcher opens a terminal menu wizard. It selects keyboard, account, hostname, timezone, locale, disk, encryption, and boot mode. The terminal entry point is:

sudo omarchy-installer --apply

Without --apply, the installer produces a read-only plan. --plain selects the plain-text interface. Review and exact confirmation precede disk changes. After storage changes begin, cancellation stops for explicit recovery rather than repeating formatting.

Fresh installations use Btrfs with @ at /, @home at /home, and @log at /var/log, with zstd compression and noatime. /nix remains on the root subvolume. Generated hosts enable automatic scrubbing. Filesystem snapshots and snapshot-based boot recovery are not implemented; Nix generation rollback does not restore personal data.

The installer offers two storage modes:

• Erase entire disk: BIOS or UEFI, with a disk of at least 32 GiB.
• Install alongside: UEFI only, on an existing GPT disk with an EFI partition and at least 33 GiB of contiguous unallocated space. It creates separate EFI and root partitions without shrinking or formatting existing partitions. The other operating system remains selectable through its existing firmware entry.

Alongside installation requires ADD <exact disk path> confirmation. Whole-disk erasure requires the disk path alone. Back up the existing operating system before partition-table changes. Complete encrypted Btrfs installation, owner handoff/reset, and booting two installed operating systems still need end-to-end acceptance.

The live image uses temporary accounts with empty passwords and passwordless sudo; remote SSH is disabled. hosts/installer.nix is installation-media configuration and must not be imported into an installed host.

Lower-level preparation, storage, and pinned-input registration helpers are packaged separately. Use their --help output and reviewed target hardware declarations when constructing a manual installation workflow. First-boot provisioning and factory reset are experimental; review modules/owner-worker.nix and modules/factory-reset.nix before enabling them on an existing host.

Build and test

Build the runtime and run focused native checks without creating result links:

nix build path:.#omarchy --no-link
nix build path:.#checks.x86_64-linux.runtime --no-link

The flake exposes additional checks for declarations, installer transactions, credentials, storage, and application integration. Run the complete flake check when the resources needed for its builds and VM tests are available:

nix flake check path:.

For graphical acceptance, build a disposable VM and pass its output path to the harness:

nix build path:.#nixosConfigurations.omarchy-vm.config.system.build.vm --no-link --print-out-paths
python3 tests/vm-smoke.py <returned-vm-path>

tests/vm-smoke.py and tests/iso-smoke.py contain the desktop and installed-media acceptance harnesses. Specialized VM configurations and focused checks are defined in flake.nix. Harnesses retain their artifacts for diagnosis; those artifacts are not project source. Native checks alone do not establish graphical login, reboot, physical graphics, or authenticated provider integration.

On this workstation, disposable build and VM workspaces belong under /data/rust/tmp. Use the configured build/cache defaults. Python bytecode and local Nix result links are ignored.

Repository layout

• hosts/: live-image and VM host declarations.
• modules/: NixOS and Home Manager options and integration.
• pkgs/: applications, wrappers, patches, and pinned asset packaging.
• runtime/: Nix-native commands and adapted desktop workflows.
• tests/: reusable checks, fixtures, and disposable VM harnesses.

The runtime replaces Arch package, update, provisioning, and reset mechanisms with Nix-backed workflows. Compatibility command names remain where needed; unavailable operations are explicitly fenced. Optional authenticated services, physical fingerprint/hibernation/graphics behavior, and broader hardware coverage remain unfinished. The experimental Dropbox package is not completed Dropbox support.

License and attribution

Original port code and documentation are MIT-licensed, copyright 2026 thesimplekid; see LICENSE. Upstream Omarchy is by David Heinemeier Hansson and retains its own MIT notice, preserved in LICENSE.omarchy. The runtime package includes both notices under share/licenses/. Dependencies, bundled application assets and third-party code retain their respective licenses; this port's license does not replace them. Upstream is pinned by the flake, and this is an independent experimental NixOS port, not a claim of upstream support.