This repository has no description
add CLAUDE.md for Claude Code guidance
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
author
lassulus
co-author
Claude
date
(Jun 14, 2025, 11:22 PM CEST)
commit
af1622ac
af1622ac04cc14b219257ccd23f207b963e68a58
parent
bb6693d7
bb6693d7c275d68217a862b40bf5b4b53cfe05ca
+82
+82
CLAUDE.md
+82
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Repository Overview
6
+
7
+
This 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
22
+
The 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
37
+
nix develop
38
+
39
+
# Run interactive menu (default package)
40
+
nix run
41
+
42
+
# Deploy to a specific machine
43
+
nix run .#deploy -- <MACHINE_NAME>
44
+
45
+
# Format code
46
+
nix fmt
47
+
48
+
# Build NixOS configuration
49
+
nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
50
+
51
+
# Build Darwin configuration
52
+
nix build .#darwinConfigurations.barnacle.system
53
+
54
+
# Access machines via SSH
55
+
ssh <machine-name>.r # via retiolum
56
+
ssh <machine-name>.s # via spora
57
+
ssh <machine-name>.n # via nether
58
+
torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
59
+
```
60
+
61
+
## Machine Facts and Secrets
62
+
63
+
Each machine stores its public facts in `machines/<name>/facts/` including:
64
+
- SSH public keys
65
+
- Network identities (retiolum, mycelium, zerotier)
66
+
- Syncthing IDs
67
+
- DKIM keys (for mail servers)
68
+
69
+
Secrets are managed via password-store and uploaded to `/etc/secrets` on deployment.
70
+
71
+
## Adding New Machines
72
+
73
+
1. Create directory `machines/<name>/`
74
+
2. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
75
+
3. Generate facts using clan-cli
76
+
4. Add to inventory in `flake.nix`
77
+
5. Deploy using `nix run .#deploy -- <name>`
78
+
79
+
## Testing
80
+
81
+
- VM tests: `./5pkgs/init/test.sh`
82
+
- Container tests are configured in `2configs/container-tests.nix`