CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A NixOS flake configuration managing multiple hosts (desktops, laptops, servers). All hosts share common settings via hosts/configuration_common.nix and are assembled in hosts/default.nix.

Common Commands

# Format all nix files
nix fmt

# Build a host configuration (no activation)
nixos-rebuild build --flake .#<host>

# Switch the current host
sudo nixos-rebuild switch --flake .#<host>

# Build a custom package
nix build .#<package>

# Edit an age-encrypted secret
agenix -e secrets/<path>.age

# Re-key all secrets after adding a new host key to secrets/secrets.nix
agenix -r

Architecture

Entry Points

flake.nix — defines inputs (nixpkgs stable=25.11, unstable, home-manager, agenix, lanzaboote, jovian-nixos, microvm, impermanence, noctalia) and calls hosts/default.nix for nixosConfigurations
hosts/default.nix — instantiates every host via lib.nixosSystem; contains the mkHM helper that wires home-manager into a host's modules list

Host Structure

Each host lives in hosts/<name>/:

default.nix — imports either ../../modules/desktop or ../../modules/server, sets the module options (myDesktop.* / myServer.*), and adds host-specific settings
home.nix — host-specific home-manager config (merged with hosts/home.nix for desktops or hosts/home_server.nix for servers)
hardware-configuration.nix — generated hardware config

Shared host-level files:

hosts/configuration_common.nix — applied to every host: SSH (key-only, no root), locale, nix GC/settings, zsh, fonts, auto-upgrade flake URL
hosts/home.nix — desktop home-manager base
hosts/home_server.nix — server home-manager base

Module System

Two top-level NixOS modules expose all major knobs as typed options:

modules/desktop/default.nix — myDesktop.*

windowManager: "niri" (default) | "sway" | "kde"
cpu: "amd" | "intel" | "none" — selects KVM kernel params
virtualisation.enable — podman (docker-compat) + qemu/libvirt + virt-manager
syncthing.{enable,devices,folders}
openrgb.{enable,motherboard}
laptop.{enable,lidSwitch,hibernateDelaySec}
nitrokey.enable
niri.hotkeyVariant: "default" | "lifebook"
git.signingKey — SSH key for commit signing
extraSystemPackages

modules/server/default.nix — myServer.*

sshPort (default 2220)
virtualisation.{enable,cpu} — podman only (no libvirt)
fail2ban.enable
autoUpgrade.enable (default true)
uid, sudoRequiresPassword, extraGroups, extraSystemPackages

Service bundles are imported as lists in host default.nix:

modules/services/server/ — kabtop services (gitea, nextcloud, matrix, coturn, hydra, mealie, etc.)
modules/services/nas/ — jupiter services (nfs, vaultwarden, syncthing, paperless)
modules/services/dmz/ — dmz services (gitea runner microVM)
modules/services/kabtopci/ — kabtopci services (hydra, gitea runner)
modules/services/nasbackup/ — nasbak backup jobs

Secrets (agenix)

secrets/secrets.nix declares which age public keys (users + host SSH keys) can decrypt each .age file. Add a new host: add its ssh-ed25519 host key to secrets/secrets.nix in the relevant groups, then run agenix -r to re-key.

Custom Packages & Overlays

packages/ — custom packages (e.g. corosync-qdevice), imported at flake.nix level
overlays/ — nixpkgs overlays applied globally
Per-host overlays: set nixpkgs.overlays inside the host's default.nix so only that host is affected

Disk Layouts

disko/ contains reusable disko modules: btrfs.nix, btrfs_luks.nix, nas_luks.nix — referenced during initial install.

Active Hosts

Host	Role	WM / Notes
hades	Desktop	niri, AMD, Secure Boot (lanzaboote)
lifebook	Laptop	niri, Intel, Secure Boot
steamdeck	Gaming	KDE/Jovian-NixOS, Secure Boot
kabtop	Main server	gitea, nextcloud, matrix+bridges, coturn, hydra, mealie
kabtopci	CI server	hydra, nix-serve
jupiter	NAS	nfs, vaultwarden, syncthing, paperless
dmz	DMZ	gitea Actions homerunner microVM
nasbak	NAS backup	—
kubemaster-1	K8s master	—

See SERVICES.md for port-level service details per host.

4.3 KiB Raw Permalink Blame History