forked from
lass.pds.lassul.us/superconfig
This repository has no description
3.2 kB
95 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 `2configs/` and `3modules/`
10- Custom packages in `5pkgs/`
11- Various network overlays (retiolum, spora, nether, zerotier, mycelium)
12
13## Key Architecture Components
14
15### Machine Management
16- **Clan-core**: Primary framework for managing multiple machines
17- **Inventory**: Machines are tagged in `flake.nix` (laptop/server tags)
18- **Secrets**: Uses password-store for secrets management via clan.core.facts
19- **Deployment**: Uses krops (via stockholm) for deployment
20
21### Network Overlays
22The repository manages multiple overlay networks:
23- **Retiolum**: VPN network (access via `.r` suffix)
24- **Spora**: Mycelium-based P2P network (access via `.s` suffix)
25- **Nether**: ZeroTier-based network overlay (access via `.n` suffix)
26- **Tor**: Anonymous network access
27
28### Module System
29- `2configs/`: Main configuration modules (imported by all machines)
30- `3modules/`: Custom NixOS module definitions
31- Stockholm modules are also imported for krebs infrastructure
32
33## Common Development Commands
34
35```bash
36# Enter development shell
37nix develop
38
39# Run interactive menu (default package)
40nix run
41
42# Deploy to a specific machine
43nix run .#deploy -- <MACHINE_NAME>
44
45# Format code
46nix fmt
47
48# Build NixOS configuration
49nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
50
51# Build Darwin configuration
52nix build .#darwinConfigurations.barnacle.system
53
54# Deploy/rebuild Darwin configuration (for barnacle)
55sudo darwin-rebuild switch --flake .#barnacle
56
57# Access machines via SSH
58ssh <machine-name>.r # via retiolum
59ssh <machine-name>.s # via spora
60ssh <machine-name>.n # via nether
61torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
62```
63
64## Important: Git Staging for Flake Evaluation
65
66**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.
67
68## Machine Facts and Secrets
69
70Each machine stores its public facts in `machines/<name>/facts/` including:
71- SSH public keys
72- Network identities (retiolum, mycelium, zerotier)
73- Syncthing IDs
74- DKIM keys (for mail servers)
75
76Secrets are managed via password-store and uploaded to `/etc/secrets` on deployment.
77
78## Adding New Machines
79
801. Create directory `machines/<name>/`
812. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
823. Generate facts using clan-cli
834. Add to inventory in `flake.nix`
845. Deploy using `nix run .#deploy -- <name>`
85
86## Testing
87
88- VM tests: `./5pkgs/init/test.sh`
89- Container tests are configured in `2configs/container-tests.nix`
90
91## Commit Message Guidelines
92
93- Use simple, descriptive commit messages without attribution footers
94- For flake.lock updates, use: "flake.lock: update"
95- Follow existing patterns seen in git log