This repository has no description
2.8 kB
83 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- 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- `2configs/`: Main configuration modules
25- `2configs/default.nix`: imported by all machines
26- `3modules/`: 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 to a specific machine
36clan machines update <MACHINE_NAME>
37
38# Format code
39nix fmt
40
41# Build NixOS configuration
42nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
43
44# Build Darwin configuration
45nix build .#darwinConfigurations.barnacle.system
46
47# Deploy/rebuild Darwin configuration (for barnacle)
48sudo darwin-rebuild switch --flake .#barnacle
49
50# Access machines via SSH
51ssh <machine-name>.r # via retiolum
52ssh <machine-name>.s # via spora
53ssh <machine-name>.n # via nether
54torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
55```
56
57## Important: Git Staging for Flake Evaluation
58
59**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.
60
61## Machine Facts and Secrets via vars
62
63- SSH public keys
64- Network identities (retiolum, mycelium, zerotier)
65- Syncthing IDs
66- DKIM keys (for mail servers)
67
68Secrets are managed via password-store and uploaded to `/run/secrets` on deployment.
69
70## Adding New Machines
71
721. Create directory `machines/<name>/`
732. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
743. Generate facts using clan-cli
754. Add to inventory in `flake.nix`
765. Deploy using `nix run .#deploy -- <name>`
77
78## Commit Message Guidelines
79
80- Use simple, descriptive commit messages without attribution footers
81- Use flake attribute paths as prefixes (e.g., `tools.mutt:` not just `mutt:`)
82- For flake.lock updates, use: "flake.lock: update"
83- Follow existing patterns seen in git log