imladris/CLAUDE.md

CLAUDE.md

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

What This Is

A flake-based NixOS configuration managing 8 hosts (all x86_64-linux). Pinned to nixpkgs nixos-26.05, with nixos-unstable available as a secondary input for select packages.

Common Commands

• Build/deploy locally: rebuild-nixos (installed to ~/.local/bin via make)
  • This runs on the target machine: pulls from local git remote, then doas nixos-rebuild switch --flake .
• Build a specific host (dry run): nixos-rebuild build --flake .#<hostname>
• Flash a remote machine: ./script/flash.sh <config-name> <ssh-address> (uses nixos-anywhere)
• Check if reboot needed: ./script/check-restart.sh
• Install the rebuild script: make

Architecture

Flake Structure

All hosts are generated via lib.genAttrs in flake.nix. Each host gets:

• disko module (declarative disk management)
• nix-index-database with comma
• Host-specific config from ./hw/<hostname>/
• Shared base from ./configuration.nix

Custom packages ke and kte are flake inputs from git.wntrmute.dev/kyle/.

Host Layout

Each host has a directory under hw/<hostname>/ containing:

• default.nix — imports hardware-config and (for desktops) desktop/qemu modules
• hardware-configuration.nix — auto-generated hardware config
• disk-config.nix — disko disk layout (where applicable)

Full desktop hosts (imladris, ono-sendai, straylight) import configs/desktop.nix; vade is a lightweight desktop importing configs/desktop-light.nix. Most desktops also import configs/qemu.nix. Server hosts (orion, rift, sk, svc) have no desktop environment; sk is minimal (hardware config + disk config only). Hosts participating in the MCP (Metacircular Control Plane) import configs/mcp.nix and configs/mcpkg.nix; straylight is becoming the core MCP host.

Shared Modules (configs/)

• pkgs.nix — system-wide packages
• desktop.nix — full desktop (builds on desktop-light.nix)
• desktop-light.nix — baseline lightweight desktop
• desktop-packages-full.nix / desktop-packages-light.nix — GUI applications
• git.nix — git identity config
• qemu.nix — QEMU/KVM virtualization
• mcp.nix / mcpkg.nix — MCP agent user/service and MCP packages

Key Design Decisions

• No home-manager — all config is system-level NixOS modules
• No overlays — packages are used directly; allowUnfree = true
• No secrets manager — SSH keys via gpg-agent, doas (not sudo) for privilege escalation
• Podman with Docker compatibility enabled on all hosts
• Tailscale and Syncthing enabled on all hosts
• LUKS encryption on most hosts (all except sk and svc)
• inputs are passed to modules via specialArgs