Skip to content
nix-config

Host Configurations

This section documents host-specific machine configurations within the fleet. Each subdirectory under hosts/ represents an individual physical system declared in outputs.nix.

[!NOTE] Shared modules—including Sunshine streaming with zero-touch tablet display, Hyprland, gaming, and shell scripts—are enabled by default across all fleet machines via outputs.nix. The table below highlights host-specific roles, hardware specifications, and quirks.

Active Fleet Inventory

HostRoleHardware SpecsBoot & StorageKey Modules & Hardware Quirks
framework16Primary Workstation LaptopFramework Laptop 16 (AMD Ryzen 7840HS, 96GB RAM)LUKS (TPM2 auto-unlock), Lanzaboote Secure Boot, Btrfs with 100GB hibernation swap (/.swapvol)QMK keyboard backlight manager (kb-light-manager), laptop power management (modules/laptop), nixos-hardware integration
mini-pc-k8HTPC / Living Room WorkstationGMKtec NucBox K8 Plus (AMD Ryzen 8845HS, 64GB RAM)Unencrypted Btrfs, 8GB swapHarmonia local binary cache (services.harmonia.cache), custom ALSA card profile (k8-plus-analog.conf), Intel Bluetooth de-authorization (8087:0029), Flatpak auto-discovery

Host Directory Structure

Every host directory follows a standardized, modular layout:

hosts/<hostname>/
├── default.nix                 # Primary entrypoint imported by outputs.nix
├── hardware-configuration.nix  # Kernel modules and drivers (auto-generated)
├── disko.nix                   # Partition scheme, filesystems, and encryption
├── config.nix                  # (Optional) Host-specific toggles, quirks, and secrets
├── flatpak.nix                 # (Optional) Host Flatpak packages (auto-imported)
└── home/                       # (Optional) Per-host Home Manager overrides
    └── default.nix

File Responsibilities

  1. default.nix: The primary NixOS configuration entrypoint for the host. Imports disko.nix, hardware-configuration.nix, and optionally config.nix.

  2. hardware-configuration.nix: Auto-generated by nixos-generate-config or during install.sh.

    [!WARNING] Never edit this file manually. Linter warnings inside auto-generated hardware configuration files are ignored by convention.

  3. disko.nix: Defines the complete disk lifecycle:

    • Partition tables (GPT, ESP /boot).
    • Disk encryption (LUKS containers and TPM2 auto-unlock via crypttabExtraOpts).
    • Filesystem formatting and subvolumes (Btrfs root, home, nix, swap).
    • Storage maintenance timers (services.btrfs.autoScrub).

  4. config.nix (Optional): A consolidated module for machine-specific option toggles, hardware workarounds, and host-specific secrets (age.secrets). For example, in mini-pc-k8, this file configures the Realtek audio workaround and disables conflicting onboard Bluetooth controllers.

  5. flatpak.nix (Optional): A dedicated list of machine-specific Flatpak packages and sandbox overrides, automatically discovered and imported by modules/flatpak/ if present.

  6. home/ (Optional): Host-specific user packages or environment settings. Automatically imported into the user’s Home Manager environment by modules/home-manager/.

Declaring Hosts in outputs.nix

Every host is wired into the system build via the hosts attribute set in outputs.nix:

<hostname> = {
  username = "<user_name>";
  system = "x86_64-linux";


  extraModules = [
    # Host-specific NixOS system modules (e.g. nixos-hardware, laptop, desktop)
  ];
};

Conventions & Best Practices

  • No Hardcoded UIDs/Paths: Always use the dynamic username variable and the users group. Never hardcode /home/username or numerical UIDs.
  • Strict Separation of Concerns: Generic or reusable capabilities belong in modules/ or home/. Only true hardware-specific quirks or host-unique settings belong in hosts/<hostname>/.
  • Minimal Diff Churn: Keep host configuration focused and avoid moving or refactoring unrelated blocks during host maintenance.