dendritic/.github/instructions/hosts.instructions.md

description, applyTo

description	applyTo
Use when defining or modifying hosts and host-local data under modules/hosts. Explains how this repo exports nixosConfigurations and homeConfigurations, when to create flake.modules.nixos or flake.modules.homeManager helpers, and how secrets, defaults, keys, and hardware files fit into a host definition.	modules/hosts/**/*.nix, modules/hosts/**/secrets.yaml, modules/hosts/**/defaults.json, modules/hosts/**/fingerprint, modules/hosts/**/*.pub

Host Definitions

Host files under modules/hosts are flake entrypoints, not just loose Nix snippets. Because modules is auto-imported through import-tree and flake-file, files here usually export one or more of these attributes:

• flake.nixosConfigurations.<name> for a bootable NixOS machine or container.
• flake.homeConfigurations.<name> for a standalone Home Manager target.
• flake.modules.nixos.<name> or flake.modules.homeManager.<name> when a host is split into reusable host-local modules that are then assembled by a nearby entrypoint.

Follow the existing host patterns in this tree:

• Keep the host entrypoint file focused on composing modules into nixosSystem or homeManagerConfiguration.
• If a host has substantial machine-specific logic, put that logic in sibling files such as configuration.nix or hardware.nix, export them as flake.modules.nixos.<name>, and have the entrypoint import those modules.
• For Home Manager only hosts, define flake.modules.homeManager.<name> and then expose a matching flake.homeConfigurations entry.
• Prefer composing from shared modules in self.modules.nixos or inputs.self.modules.homeManager instead of re-implementing shared behavior inline.

Treat host-local data as part of the host definition:

• Keep hardware-specific settings in the host directory, typically in hardware.nix.
• Keep install-time or machine-specific configuration in the same host directory, typically in configuration.nix.
• Keep host-local secret references beside the host and wire them through sops.defaultSopsFile and mysops.hostSecretFile instead of pointing at unrelated locations.
• Preserve nearby auxiliary files such as defaults.json, fingerprints, public keys, and secrets.yaml; these are part of the host contract.

For host-adjacent data files:

• Keep secrets.yaml scoped to the host that consumes it; do not reuse another host's secret file as a shortcut.
• Treat files such as defaults.json, fingerprint, and *.pub as inputs consumed by the host module. Update references together with the data when changing paths or filenames.
• Avoid moving or renaming these files unless the corresponding Nix references are updated in the same change.

Naming in this tree is not perfectly uniform, so preserve existing interfaces unless the task is explicitly a rename:

• The directory name, exported flake key, and networking.hostName may differ.
• Some hosts export from default.nix, while others keep the main definition in a differently named file such as soteria.nix.
• Do not normalize names or move files just for consistency unless the user asks for that structural change.

Naming rules for new hosts:

• Treat the host directory name as the canonical host slug for new work.
• Prefer modules/hosts/<slug>/default.nix as the main entrypoint for a host directory.
• Use the same slug for the primary hostname binding, flake.nixosConfigurations.<slug>, and networking.hostName unless the task explicitly requires a different deployed hostname.
• If the host exports a host-local Home Manager module, name it flake.modules.homeManager.<slug>.
• For standalone Home Manager configurations, prefer flake.homeConfigurations."<username>@<slug>" so the exported key still carries the host slug.
• Name host-local helper modules with the same slug as a prefix, for example flake.modules.nixos.<slug>-hardware or flake.modules.nixos.<slug>-configuration, to make ownership obvious and avoid collisions with shared modules.
• Keep host-local secrets and auxiliary files under the same host slug directory. Do not point a new host at another host's path just because the contents are similar.

Allowed exception for immutable deployed hostnames:

• If the deployed hostname is externally constrained and cannot change, use that deployed hostname as the canonical slug for exported keys and hostname bindings, even if the directory name differs.
• In that case, keep the exception explicit in comments or reports so future cleanup work does not accidentally rename a live hostname contract.

When working in existing hosts that predate these rules:

• Preserve the current public names by default.
• If the user asks for a rename or cleanup, update the directory slug, exported flake keys, host-local module names, and networking.hostName together in one change so the host identity stays coherent.

Use nearby hosts as composition examples:

• john-p14s splits the reusable machine logic into configuration.nix and hardware.nix, exports flake.modules.nixos.p14sConfiguration and flake.modules.nixos.p14sHardware, and assembles them from default.nix.
• janus defines a host-local reusable module (flake.modules.nixos.janus-ca) in the same file that also exports the final flake.nixosConfigurations.janus host.
• john-pc is a Home Manager target, so it exports a flake.modules.homeManager module and a flake.homeConfigurations entry rather than a nixosConfiguration.
• soteria combines a NixOS host, a host-local Home Manager module, and host-local secrets in one host directory.

When adding or changing a host:

• Mirror the local style first. Small hosts may define the full configuration inline; larger hosts should split reusable modules out.
• Keep let bindings such as username, hostname, flakeDir, and package aliases near the top when the file already follows that pattern.
• Add shared behavior by importing existing modules, not by copying option blocks between hosts.
• If the change affects both system and Home Manager state for a host, update both sides in the same host area when that host already models both.

For reviews and answers, distinguish between these layers:

• host entrypoint wiring in modules/hosts/...
• reusable shared modules in modules/nixos, modules/programs, modules/services, and modules/users
• host-local modules exported from a host directory and then consumed by its entrypoint