Nix-based system configuration using the dendritic pattern with flake-parts and clan-core.
- Adding New Machines - Complete guide for onboarding new NixOS/Darwin machines
- Troubleshooting Clan Commands - Debug common deployment issues
- Secrets and Key Management - Machine keys vs user keys, SSH-derived keys, anti-patterns
- Router Module - Complete router with VLAN, WiFi, firewall, DHCP, DNS, SQM
- WireGuard Split Tunneling - Route specific services through a VPN using network namespaces
- Service Exposure Pathways - Private (Caddy/LAN/WG) and public (Cloudflare Tunnel) service access
- Web Hosting Setup - Self-hosting websites via DDNS + reverse proxy (in progress)
# From admin workstation
clan vars upload <hostname>
clan machines update <hostname>- Create
machines/<hostname>/configuration.nix - Add to
modules/flake-parts/clan.nixinventory - Generate secrets:
clan vars generate <hostname> - Deploy:
clan machines update <hostname>
See Adding New Machines for detailed steps.
dotfiles/
├── machines/ # Host-specific configurations
├── modules/ # Reusable NixOS/Darwin/home-manager modules
│ └── flake-parts/ # Flake infrastructure (clan, nixpkgs, shell)
├── home-profiles/ # User environment compositions
├── sops/ # Secrets management
│ ├── machines/ # Machine public keys
│ ├── secrets/ # Encrypted secrets (age keys, passwords)
│ └── secrets.yaml # App secrets (traditional sops-nix)
└── vars/ # Clan-managed variables
├── per-machine/ # Machine-specific vars
└── shared/ # Cross-machine vars
This repo uses a hybrid approach:
| System | Purpose | Location |
|---|---|---|
| Clan vars | Machine bootstrap, user passwords, SSH keys | vars/, sops/secrets/<machine>-age.key/ |
| Traditional sops-nix | App secrets (tailscale, borg, etc.) | sops/secrets.yaml |
- Clan-generated keys: Fresh age keypairs created by clan, stored encrypted in repo
- Machine key.json: Public key used to encrypt secrets FOR a machine
- Self-upload: Machine can decrypt its own bootstrap secrets
- Admin upload: Admin workstation decrypts and uploads to machine
# Machine deployment
clan machines list # List all machines
clan machines update <hostname> # Deploy to machine
clan vars upload <hostname> # Upload secrets only
# Secrets management
clan vars list <hostname> # List vars for machine
clan vars generate <hostname> # Generate vars
clan secrets get <secret> # Decrypt a secret
clan secrets machines add-secret <m> <s> # Add machine as recipient
# Development
nix develop # Enter dev shell
nix fmt # Format all files
nix flake check # Validate flake| Hostname | Type | OS | Description |
|---|---|---|---|
| pp-ml1 | Laptop | Darwin | Personal MacBook |
| pp-ll1 | Laptop | NixOS | Personal Linux laptop |
| pp-ld1 | Desktop | NixOS | Personal Linux desktop |
| pp-nas1 | Server | NixOS | NAS (BeeLink) |
| pp-router1 | Server | NixOS | Router |
| pp-rpi1 | SBC | NixOS | Raspberry Pi 3B+ GPIO debugger |
| pp-wsl1 | VM | NixOS | WSL instance |