nixos-config/hosts/common/AGENTS.md

COMMON HOST CONFIGURATION

Shared base configuration and abstractions for all hosts

OVERVIEW

Common imports, overlays, and custom patterns (extraServices, ports) used across 6 hosts.

STRUCTURE

common/
├── default.nix          # Base imports, overlays, nix settings
├── ports.nix            # Centralized port registry
├── extraServices/       # Optional service modules
│   ├── default.nix
│   ├── flatpak.nix
│   ├── ollama.nix
│   ├── podman.nix
│   └── virtualisation.nix
└── users/
    ├── default.nix
    └── m3tam3re.nix     # Primary user definition

WHERE TO LOOK

Task	Location	Notes
Add port definition	ports.nix	Use config.m3ta.ports.get
Enable optional service	Host config extraServices	Boolean flags
Modify overlays	default.nix lines 27-36	5 overlay sources
Add new user	users/	Shared across all hosts

CONVENTIONS

Port Registry Pattern

# Define in ports.nix
definitions = {
  myservice = 3099;
};

# Access in host config
config.m3ta.ports.get "myservice"  # Returns 3099

extraServices Abstraction

Host configs enable via boolean:

extraServices = {
  podman.enable = true;      # Container runtime
  ollama.enable = true;      # LLM inference
  flatpak.enable = false;    # Flatpak apps
  virtualisation.enable = true;  # QEMU/KVM
};

Overlay Precedence (bottom overrides top)

1. stable-packages (nixpkgs-stable)
2. locked-packages (nixpkgs-locked)
3. pinned-packages (nixpkgs-45570c2, nixpkgs-9e58ed7)
4. master-packages (nixpkgs-master)
5. m3ta-nixpkgs (local custom overlay)

ANTI-PATTERNS

• DON'T add host-specific logic to common/ - belongs in hosts//
• DON'T bypass port registry - hardcoded ports break consistency
• DON'T modify user shell globally - set per-user if needed

NOTES

• Nix GC runs weekly, keeps 30 days
• Trusted users: root, m3tam3re
• Default shell: Nushell (set line 77)
• Home-manager integrated at common level, not per-host
• TODO on line 69: ports should only return actually used ports