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
• FredOS-Rescue — live rescue USB that boots into Claude Code (nix build .#rescue-iso; prompt + greeting in hosts/rescue/)

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, …)
• walls/ — wallpapers. settings/theming.nix builds a full theme per image (base16 palette + rendered config for GTK, ghostty, btop, hyprland, vesktop, zen, folder icons); the bar's wallpaper button switches between them at runtime via theme-apply, no rebuild. walls/wallpaper.png stays stylix's build-time image.
• 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 normally build from the Forgejo remote. On the mediaserver, update and update2 call fred-deploy, sharing a guarded deployment transaction with the router UI and nightly update. Clients build on the server, copy the closure, then switch locally. See docs/deployment.md for server deployment and recovery. 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:

# 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.