dotfiles/CLAUDE.md

CLAUDE.md

NixOS + nix-darwin dotfiles managing multiple hosts via a single flake. Uses flake-parts, import-tree, home-manager, and agenix for secrets.

Hosts

Host	Platform	Role
endurance	nixos (x86_64-linux)	Desktop workstation (AMD GPU, Niri compositor)
aepplet	nixos (x86_64-linux)	Data/compute server
vasa	darwin (x86_64-darwin)	macOS (minimal config)

Host configs live in hosts/{name}/ with default.nix, hardware.nix, and disko.nix.

Key directories

Path	What's there
flake.nix	Entry point — all inputs and flake-parts imports
modules/flake/	Flake-parts modules: host definitions, home-manager wiring, packages, formatter, lib
modules/generic/	Shared config (nix settings, profiles, base packages) — applies to all platforms
modules/nixos/	NixOS-specific: system, users, SSH, services (ollama, traefik, beszel, metrics)
modules/nixos/profiles/	Composable feature profiles: graphical, docker, work
modules/darwin/	macOS-specific modules
modules/home/	Home-manager modules shared across hosts (helix, terminal, shell, kitty, GUI)
home/by-host/{name}/	Per-host home-manager config (programs, services, theming)
home/by-host/{name}/config/	Auto-imported config modules (dev, shell, git, etc.)
home/by-host/{name}/misc/	Optional per-host services (launcher, browser, recording)
home/by-host/{name}/niri/	Niri WM config (keybinds, window rules, autostart)
packages/	Custom packages (each dir has package.nix, auto-discovered)
overlays/	Nixpkgs overlays (lix, unstable channel packages, custom builds)
secrets/	Age-encrypted secrets managed by agenix

Custom options namespace

This flake uses a bosun namespace for composable options:

bosun.profiles.graphical.enable = true;
bosun.profiles.docker.enable = true;
bosun.profiles.work.enable = true;
bosun.key = "ssh-ed25519 ...";      # Host SSH public key
bosun.secrets.npmrc = { ... };       # Secret definitions

Profile definitions are in modules/generic/profiles.nix, implementations in modules/nixos/profiles/.

Adding packages

Before writing a custom packages/ derivation, always check if the package already exists in nixpkgs:

• Stable: https://search.nixos.org/packages?channel=25.11&query=
• Unstable: https://search.nixos.org/packages?channel=unstable&query=
• Master (bleeding edge): check open PRs at https://github.com/NixOS/nixpkgs/pulls

If it exists in unstable or master but not stable, pull it via overlays/unstable.nix using channels.unstable or channels.master. Only write a custom packages/ derivation as a last resort.

Architecture patterns

• import-tree auto-discovers and imports .nix files in modules/flake/. Files prefixed with _ are excluded from auto-import.
• easy-hosts manages host definitions in modules/flake/hosts.nix.
• Overlays receive inputs and channels (multiple nixpkgs instances) via the withChannels wrapper in overlays/default.nix.
• Stylix handles system-wide theming (colors, fonts) from a single config.
• Lix is used instead of stock Nix.

Commands (just)

just deploy          # nixos-rebuild switch / darwin-rebuild switch
just debug           # Build with --show-trace --verbose via nom
just repl            # nix repl with flake loaded
just shell <name>    # Enter a dev shell
just up              # Update all flake inputs
just upp <input>     # Update a single input
just gc              # Garbage collect old generations
just rekey           # Rekey all agenix secrets
just edit-secret <f> # Edit an encrypted secret

Where to find settings

Looking for...	Go to
Which hosts exist and their platform	modules/flake/hosts.nix
Home-manager host assignments	modules/flake/homes.nix
Nix daemon settings, substituters, gc	modules/generic/nix.nix
Locale, timezone, stateVersion	modules/nixos/system.nix
User accounts	modules/nixos/users.nix
SSH daemon config	modules/nixos/ssh.nix
Shell config (Fish, Nushell)	modules/home/common/terminal/shell/
Helix editor config	modules/home/common/helix/
Kitty terminal	modules/home/gui/kitty.nix
Desktop programs for endurance	home/by-host/endurance/config/dev.nix and misc/
Niri keybinds & window rules	home/by-host/endurance/niri/
Available packages	packages/ (auto-discovered by flake-parts)
Secret definitions	modules/*/secrets.nix + secrets/*.age