This repository has no description
5.1 kB
128 lines
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Repository Overview
6
7This is lassulus's personal NixOS/nix-darwin configuration repository, built on clan-core for managing multiple machines. It includes:
8- Multiple machine configurations in `machines/`
9- Configuration modules in `configs/` and `modules/`
10- Custom packages in `pkgs/`
11- packages which could in theory be upstreamed to nixkgs should go into the pkgs folder, in the tools folder we add tools we write ourself which are more complex or not upstreamable
12
13## Key Architecture Components
14
15### Machine Management
16- **Clan-core**: Primary framework for managing multiple machines
17- **Secrets**: Uses password-store for secrets management via clan.core.vars
18
19### Network Overlays
20The repository manages multiple overlay networks:
21- **Tor**: Anonymous network access
22
23### Module System
24- `configs/`: Main configuration modules
25- `configs/default.nix`: imported by all machines
26- `modules/`: Custom NixOS module definitions
27- Stockholm modules are also imported for krebs infrastructure
28
29## Common Development Commands
30
31```bash
32# Enter development shell
33nix develop
34
35# Deploy a NixOS machine (tools/deploy): one Secure Enclave unlock for all
36# secrets, builds on the target, shows source/closure diff, asks before
37# switching. `s` runs apps from ~/src/superconfig, so pass --flake to deploy
38# a different checkout/worktree. NEVER use `clan machines update`: it
39# decrypts each secret separately and fails on the Secure Enclave prompt.
40s deploy --flake . <MACHINE_NAME>
41
42# Agents: deploy only when the user asked for it, and then always with
43# --yes. Without it the run stops at the [y/N] switch prompt (and the source
44# diff can wait in a pager) and looks hung. --yes skips both; the diffs are
45# still printed, so read them in the output afterwards.
46s deploy --flake . --yes <MACHINE_NAME>
47
48# Format code
49nix fmt
50
51# Build NixOS configuration
52nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
53
54# Build Darwin configuration
55nix build .#darwinConfigurations.barnacle.system
56
57# Deploy/rebuild Darwin configuration (for barnacle)
58sudo darwin-rebuild switch --flake .#barnacle
59
60# Access machines via SSH (as root, see below)
61ssh root@<machine-name>.r # via retiolum
62torify ssh root@$(pass show machines/<machine-name>/tor-hostname) # via tor
63```
64
65## Remote Machine Access
66
67**CRITICAL**: For privileged work on a remote machine (firewall rules,
68journals of system services, systemctl, reading /run/secrets, ...), ssh in as
69root (`ssh root@<machine>.r`). NEVER use `sudo` on remote systems. Ssh as the
70normal user (`lass@`) only to act as that user, e.g. to run user tools.
71
72## Important: Git Staging for Flake Evaluation
73
74**CRITICAL**: New nix files must be staged (git add) before they are available in flake evaluation. When creating new packages, modules, or any nix files, always run `git add <files>` before testing with `nix build`, `nix run`, etc.
75
76## Git Push Policy
77
78**CRITICAL**: NEVER `git push` to any remote. Local commits are fine when asked.
79A push happens only when the user runs it themselves or explicitly says
80"push" for that specific change in the current conversation. This includes
81all remotes (origin, HTTPS via gh credentials, pair) and all branches.
82
83Changes reach master through pull requests, not direct pushes: a ruleset on
84master requires a PR whose `ci` check (`.github/workflows/ci.yml`) passed.
85When the user says "push", push the branch and let GitHub merge it once CI
86is green:
87
88```bash
89git fetch github && git rebase github/master
90git push github HEAD:<branch>
91gh pr create --base master --head <branch> --fill
92gh pr merge <branch> --auto --rebase --delete-branch
93```
94
95`--rebase` keeps the individual commits on master. Only the user (repo admin)
96bypasses the ruleset. The `ci` check includes the build of all NixOS
97machines on GitHub runners, with hestia (GitHub Actions cache) as binary
98cache; every CI build is pushed to cache.lassul.us (niks3), so deploys
99substitute the toplevels from there. The update-pkgs bot's PRs go through
100the ruleset as well: they run ci.yml like any PR and merge via auto-merge.
101
102## Machine Facts and Secrets via vars
103
104- SSH public keys
105- Network identities (retiolum, zerotier)
106- Syncthing IDs
107- DKIM keys (for mail servers)
108
109Secrets are managed via password-store and uploaded to `/run/secrets` on deployment.
110
111## Adding New Machines
112
1131. Create directory `machines/<name>/`
1142. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
1153. Generate facts using clan-cli
1164. Add to inventory in `flake.nix`
1175. Deploy using `s deploy --flake . <name>` (agents add `--yes`)
118
119## Pre-Commit
120
121**CRITICAL**: Always run `nix fmt` before committing to ensure all files pass the treefmt formatting check in CI.
122
123## Commit Message Guidelines
124
125- Use simple, descriptive commit messages without attribution footers
126- Use flake attribute paths as prefixes (e.g., `tools.mutt:` not just `mutt:`)
127- For flake.lock updates, use: "flake.lock: update"
128- Follow existing patterns seen in git log