nixos/CLAUDE.md

# FredOS NixOS Configuration

This is a NixOS flake-based configuration for multiple hosts:
- **FredOS-Gaming** — gaming desktop
- **FredOS-Mediaserver** — home media server **and the home router** (nftables NAT/firewall in `services/router.nix`; `networking.firewall` is disabled on this host, WAN exposure comes from `ports.toml`)
- **FredOS-Macbook** — MacBook laptop

## Structure

- `flake.nix` — flake inputs/outputs; all hosts track the `nixos-26.05` stable channel
- `common.nix` — shared configuration across all hosts
- `hosts/` — per-host NixOS configuration modules (imported per-host by `mkHost` in flake.nix)
- `hosts/hardware/` — hardware-specific configuration
- `home-manager/` — Home Manager configuration (via NixOS module)
- `services/` — modular service definitions, gated by hostname with `lib.mkIf`
- `settings/` — shared settings (desktop, hyprland, quickshell, stylix, …)
- `modules/crowdsec/` — vendored crowdsec modules from nixpkgs PR #446307; delete once that PR lands in the pinned channel
- `ports.toml` — WAN → LAN port forwards consumed by `services/router.nix`

## Deployment

Hosts never pull this repo locally — they rebuild from the Forgejo remote via the
`update` alias (`nixos-rebuild switch --refresh --flake git+https://forg.gregersen.it/rope/nixos`).
That means evaluation is **pure**: config can never read files outside the repo
(e.g. `/var/secrets`) at eval time. Secrets must be injected at service runtime
(see `services/crowdsec.nix` and `services/go2rtc.nix` for the pattern).

## Code Evaluation

Before writing or changing any NixOS / Home Manager option, verify it exists and
has the expected name and type using the `nixos` MCP server tools (`nix` /
`nix_versions`, configured in `.mcp.json`). Don't rely on memory for option or
package names — look them up first to avoid invented attributes that fail at eval.

Always validate Nix expressions with `nix eval` before committing. For example:

```bash
# Evaluate a specific attribute to check for syntax/type errors
nix eval .#nixosConfigurations.FredOS-Gaming.config.system.stateVersion

# Full eval of a host without building
nix eval --raw .#nixosConfigurations.FredOS-Mediaserver.config.system.build.toplevel.drvPath

# Evaluate the full flake outputs to catch top-level errors
nix eval .#nixosConfigurations --apply builtins.attrNames
```

Use `nix flake check` for a broader check of the flake.