Architecture

This page is the map of the repository: what lives where, how a host gets built, and where to start when adding something new.

Directory layout

How a host is built

flake.nix
  └─ systems/default.nix          scans systems/<arch>/ for host directories
       ├─ arch contains "darwin"? ─ nix-darwin's darwinSystem
       │    └─ modules/darwin + home-manager + stylix + sops + homes/nixos.nix
       └─ otherwise ─────────────── lib.nixosSystem
            └─ modules/nixos + home-manager + facter + homes/nixos.nix
                 └─ homes/nixos.nix instantiates home-manager for
                    homes.users (default: the primary user), each importing
                    homes/<user>/ + modules/home-manager

• networking.hostName is forced to the directory name.
• A facter.json in the host directory is picked up automatically (hardware detection via nixos-facter).
• A nixpkgs.nix in the host directory supplies per-host nixpkgs config, merged over the shared one. This is the only way to set it: pkgs is instantiated in systems/default.nix outside the module system, so a host cannot use nixpkgs.config in its configuration.nix (the nixpkgs module rejects it). See systems/x86_64-linux/kyuubi/nixpkgs.nix, which permits an insecure Broadcom wifi driver for that host alone.
• users.primaryUser must be set in every host config; the user account itself comes from modules/nixos/users/ (or modules/darwin/users/).
• Standalone homeConfigurations.<user> (for non-NixOS machines) are generated from the homes/<user>/ directories, independent of any host.

The tag system

Hosts describe themselves with a list of tags instead of toggling dozens of options:

# systems/x86_64-linux/madara/configuration.nix
system.tags = [ "desktop" "workstation" "development" "management" ];

• The known tags are enumerated in modules/shared/tags.nix — the option type rejects anything else at eval time, so a typo or a tag without consumers cannot slip in silently. Current tags: desktop, laptop, workstation, development, management, nas, gaming, server (each with a one-line meaning in that file).
• Modules query tags through config.lib.tags.hasTag "<tag>" (the predicate lives in lib/has-tag.nix; the option is declared under modules/{nixos,darwin}/system/tags/).
• Tag modules under modules/{nixos,darwin}/system/tags/ translate tags into concrete settings (e.g. desktop enables the desktop environment stack, management installs colmena, gaming enables Steam). Server roles key on the server tag — tailscale exit-node/connector/SSH advertising and the no-sound-stack default — never on the absence of an interactive tag: a workstation or laptop without desktop is still somebody’s machine.
• Colmena reuses the same tags for deployment targeting: colmena apply --on @desktop (wired via colmena.deployment.tags).
• Home Manager cannot read config.lib.tags without infinite recursion, so modules/home-manager/imports.nix imports the predicate directly against osConfig and maps tags onto its own hosts.{desktop,laptop,workstation,development}.enable options. Inside home-manager modules, gate on config.hosts.*.enable.

Background vs foreground

modules/home-manager/ is split by session type, not by program category:

• background/ — everything that works on a headless machine or over SSH: shell, git, editors, CLI tools, AI tooling, user services. Imported unconditionally.
• foreground/ — everything that needs a display: desktop environments, bars, GUI programs, fonts-for-GUI. Gated behind foreground.enable, which defaults from the desktop tag (darwin), the gui.enable option (NixOS), or true (standalone home-manager).
• theming/ — stylix wiring, wallpaper, color scheme; enabled with the desktop tag.
• development/ — policy: which languages/tools from modules/devix (the mechanism) are turned on for development-tagged hosts.

devix

Development-environment mechanism: describe a language once — its language servers, formatters and indentation — and every editor that consumes the description configures itself from it. Stylix’s idea, applied to dev tooling.

It is documented in its own section, starting at devix: concepts, usage, adding a language, adding an editor, and a generated support matrix and option reference.

The one thing worth repeating here is the split this repository depends on: modules/devix is pure mechanism and enables nothing, while modules/home-manager/development/ is the policy that decides which languages are on for which hosts.

Adding a host

1. Create systems/<arch>/<hostname>/default.nix (plus configuration.nix, hardware-configuration.nix or facter.json, and optionally disk.nix for disko). The directory is discovered automatically.
2. Set users.primaryUser and system.tags in the config.
3. Add the host’s age key to secrets/.sops.yaml and re-encrypt: just secrets-rekey (key comes from the host’s SSH key, see sops).
4. For colmena deploys, set colmena.deployment.targetHost.
5. If the host should get an installer image, add it to the list in systems/iso/default.nix — then just iso <hostname>.

Adding a user

1. Create homes/<user>/default.nix (auto-discovered as homeConfigurations.<user>); put SSH public keys in homes/<user>/keys/.
2. Create modules/nixos/users/<user>.nix (auto-imported; see mirza.nix for the pattern).
3. Set users.primaryUser = "<user>" on the hosts that belong to them, and add their age key to secrets/.sops.yaml.

Custom options cheat sheet

Options defined by this flake (as opposed to upstream NixOS/HM options):

NAS behaviour follows the nas tag, and the TPM2 stack is driven by the upstream security.tpm2.enable (this flake just layers PKCS11/tooling on top).

New custom options should be namespaced (or documented here) so they stay distinguishable from upstream options.