---
description: "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."
applyTo: '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