main

Shared NixOS Configuration

Code in this directory is used by all hosts across both nixpkgs channels (unstable and stable/25.11). See ../AGENTS.md for the full channel map.

Rules for Modifying Shared Code

  1. Never assume an option exists on all channels. Options added or renamed in nixpkgs-unstable won’t exist on nixpkgs-25.11 (and vice versa for backports). When in doubt, check the option exists before using it.

  2. Use conditional patterns when a change is channel-dependent:

    # Check if an option exists before using it
lib.optionalAttrs (builtins.hasAttr "newOption" options.services.foo) {
  services.foo.newOption = true;
}

# Version-gated setting
lib.mkIf (lib.versionAtLeast config.system.nixos.release "25.11") {
  services.foo.bar = "new-value";
}

  3. Prefer host-specific overrides over conditionals when the change only affects one or two hosts. Edit systems/<hostname>/extra.nix instead of modifying shared modules.

  4. Test both channels after modifying shared code:

    • Unstable: make host/okinawa/build
    • Stable: make host/rhea/build

Directory Structure

  • base/ — core system settings (nix, boot, locale, networking, security)
  • desktop/ — desktop environment modules (sway, niri, waybar, etc.)
  • hardware/ — hardware support (audio, bluetooth, GPU, etc.)
  • programs/ — system-wide program configurations
  • services/ — system service configurations
  • users/ — user account definitions