heavily inspired by https://tangled.org/quasigod.xyz/nixconfig
llm docs
Herschel Pawar
(Jun 3, 2026, 7:35 PM +0530)
bf9310f1
bb73d9c5
+77
-24
+3
-3
to-kat/adding-new-hosts.md
+3
-3
to-kat/adding-new-hosts.md
···
29
29
nixos =
30
30
{ pkgs, ... }:
31
31
{
32
-
system.stateVersion = "23.05"; # ← set to the NixOS version at install time
32
+
system.stateVersion = "26.05"; # ← set to the NixOS version at install time (check with nixos-version)
33
33
};
34
34
};
35
35
}
···
109
109
{
110
110
den.hosts.x86_64-linux = {
111
111
kats-laptop.users = { ... };
112
-
wsl.users.ksakura = { };
112
+
kats-wsl.users.ksakura = { };
113
113
<hostname>.users = {
114
114
ksakura = { }; # full user with home-manager
115
115
# kat = { classes = [ ]; }; # SSH-only, no home-manager
···
160
160
];
161
161
162
162
nixos = { pkgs, ... }: {
163
-
system.stateVersion = "25.05";
163
+
system.stateVersion = "26.05";
164
164
environment.systemPackages = with pkgs; [ firefox ];
165
165
};
166
166
};
+1
-1
to-kat/adding-new-users.md
+1
-1
to-kat/adding-new-users.md
+7
-6
to-kat/architecture-overview.md
+7
-6
to-kat/architecture-overview.md
···
78
78
├─ hosts/
79
79
│ ├─ default.nix ← entity declarations (which users on which hosts)
80
80
│ ├─ kats-laptop/ ← host-specific aspects
81
-
│ ├─ wsl/
82
-
│ └─ rpi/
81
+
│ ├─ kats-wsl/
82
+
│ └─ kats-rpi/
83
83
├─ users/
84
84
│ ├─ ksakura.nix ← provides.to-hosts → injects user into hosts
85
85
│ └─ kat.nix ← unprivileged SSH user
···
92
92
│ ├─ programs/ ← per-tool aspects (atuin, helium, helix, jujutsu, etc.)
93
93
│ └─ system/ ← kernel, bootloader, fstrim, ssh, tmpfs, zram
94
94
└─ overlays/
95
-
├─ helium.nix ← adds helium browser to nixpkgs
96
-
└─ nil.nix ← pins nil LSP to a specific revision
95
+
├─ helium.nix ← adds helium browser to nixpkgs
96
+
├─ nil.nix ← pins nil LSP to a specific revision
97
+
└─ pi-coding-agent.nix ← adds pi-coding-agent to nixpkgs (used by kats-laptop)
97
98
```
98
99
99
100
### How a Build Happens
···
112
113
x86_64-linux:
113
114
├─ kats-laptop ← ThinkPad T480 (full desktop: GNOME, all programs, hardware support)
114
115
│ users: ksakura (full), kat (SSH-only)
115
-
└─ wsl ← Windows Subsystem for Linux (minimal CLI)
116
+
└─ kats-wsl ← Windows Subsystem for Linux (minimal CLI)
116
117
users: ksakura
117
118
118
119
aarch64-linux:
119
-
└─ rpi ← Raspberry Pi (minimal CLI, headless)
120
+
└─ kats-rpi ← Raspberry Pi (minimal CLI, headless)
120
121
users: ksakura
121
122
```
122
123
+1
to-kat/aspects-base-cli-gui-hardware-networking-programs-system.md
+1
to-kat/aspects-base-cli-gui-hardware-networking-programs-system.md
···
211
211
|---|---|
212
212
| `helium.nix` | Adds `helium` browser to nixpkgs from `github:ominit/helium-browser-flake`. |
213
213
| `nil.nix` | Pins `nil` (Nix LSP) to a specific revision with a custom `cargoHash`. |
214
+
| `pi-coding-agent.nix` | Adds `pi-coding-agent` to nixpkgs from `github:numtide/llm-agents.nix`. Included by kats-laptop. |
214
215
215
216
Overlays declare their own flake inputs, so removing the overlay removes the dependency:
216
217
+2
-2
to-kat/common-tasks.md
+2
-2
to-kat/common-tasks.md
+33
-6
to-kat/files-vm-nh-dendritic-defaults.md
+33
-6
to-kat/files-vm-nh-dendritic-defaults.md
···
12
12
13
13
```nix
14
14
# den + flake-file wiring. nixpkgs and home-manager kept in sync.
15
-
{ inputs, ... }:
15
+
{ inputs, den, ... }:
16
16
{
17
17
imports = [
18
18
(inputs.flake-file.flakeModules.dendritic or { })
19
19
(inputs.den.flakeModules.dendritic or { })
20
+
inputs.agenix-rekey.flakeModule
21
+
inputs.home-manager.flakeModules.home-manager
20
22
];
23
+
24
+
den.schema.user.includes = [ den._.mutual-provider ];
21
25
22
26
systems = [
23
27
"x86_64-linux"
···
40
44
41
45
| Line | Meaning |
42
46
|---|---|
43
-
| `imports = [ ... ]` | Imports the `dendritic` flake module from both `flake-file` and `den`. The `or { }` prevents errors if the module isn't found. |
47
+
| `imports = [ ... ]` | Imports the `dendritic` flake module from both `flake-file` and `den`, plus `agenix-rekey` and `home-manager` flake modules. The `or { }` prevents errors if the module isn't found. |
48
+
| `den.schema.user.includes` | Adds the `mutual-provider` battery to every user, enabling host→user and user→host config forwarding (e.g., `provides.to-users`, `provides.<username>`). |
44
49
| `systems = [ ... ]` | Architectures this config targets. Both x86_64 (laptops, WSL) and aarch64 (Raspberry Pi). |
45
50
| `flake-file.inputs.den` | The `den` framework itself. |
46
51
| `flake-file.inputs.flake-file` | Auto-flake generator. |
47
52
| `flake-file.inputs.nixpkgs` | Pinned to `nixos-26.05` (stable). |
48
-
| `flake-file.inputs.home-manager` | Pinned to `release-26.05`, following the same nixpkgs. Keeps home-manager and nixpkgs in sync. |
53
+
| `flake-file.inputs.home-manager` | Pinned to `release-26.05`, following the same nixpkgs. Keeps home-manager and home-manager in sync. |
49
54
50
55
### Why a Single Wiring File?
51
56
···
61
66
62
67
```nix
63
68
# den.default — applied to every host and user automatically.
64
-
{ lib, den, ... }:
69
+
{
70
+
lib,
71
+
den,
72
+
self,
73
+
inputs,
74
+
...
75
+
}:
65
76
{
66
77
den.default.includes = [
67
78
den.batteries.hostname
68
79
(den.batteries.define-user { })
69
80
];
70
81
82
+
den.default.nixos = {
83
+
home-manager.backupFileExtension = "bk";
84
+
85
+
nix.settings.experimental-features = [ "nix-command" "flakes" ];
86
+
87
+
environment.etc."nixos-config" = { source = ../.; };
88
+
89
+
system.configurationRevision = lib.mkDefault (
90
+
inputs.self.rev or self.rev or "dirty"
91
+
);
92
+
};
93
+
71
94
den.schema.user.classes = lib.mkDefault [ "homeManager" ];
72
95
}
73
96
```
···
78
101
|---|---|
79
102
| `den.batteries.hostname` | Auto-sets `networking.hostName` to the host entity name. You don't need `networking.hostName = "kats-laptop"` anywhere — it's automatic. |
80
103
| `den.batteries.define-user { }` | Auto-creates `users.users.<name>.isNormalUser = true` for every user declared in `hosts/default.nix`. With empty args, uses defaults. |
104
+
| `home-manager.backupFileExtension` | If home-manager would overwrite an existing dotfile, it renames the old one with a `.bk` suffix instead of failing. Prevents activation errors on existing `gh/config.yml`, `jj/config.toml`, `atuin/config.toml`, etc. |
105
+
| `nix.settings.experimental-features` | Required for flakes. |
106
+
| `environment.etc."nixos-config"` | Captures the full flake source in the Nix store, so it's available at runtime (safe from accidental deletion). |
107
+
| `system.configurationRevision` | Tags the generation with the git/jj revision for rollback identification. |
81
108
| `den.schema.user.classes` | Sets the default user class to `[ "homeManager" ]`, meaning home-manager config runs for every user unless overridden (see `kat` user). |
82
109
83
110
### `lib.mkDefault` and Overrides
···
115
142
116
143
```
117
144
packages.x86_64-linux.kats-laptop
118
-
packages.x86_64-linux.wsl
119
-
packages.aarch64-linux.rpi
145
+
packages.x86_64-linux.kats-wsl
146
+
packages.aarch64-linux.kats-rpi
120
147
```
121
148
122
149
`nh` finds these and lets you run:
+11
-6
to-kat/secrets-management.md
+11
-6
to-kat/secrets-management.md
···
15
15
│
16
16
agenix-rekey
17
17
│
18
-
┌──────────┼──────────┐
19
-
│ │ │
20
-
┌────▼────┐ ┌──▼──┐ ┌───▼───┐
21
-
│kats- │ │kats-│ │kats- │ ← per-host encrypted
22
-
│laptop │ │wsl │ │rpi │ copies in secrets/
23
-
└─────────┘ └─────┘ └───────┘
18
+
┌──────────┼──────────────────┐
19
+
│ │ │
20
+
┌────▼────┐ ┌──▼──────────┐ ┌──────────▼───┐
21
+
│kats- │ │kats- │ │kats- │ ← per-host encrypted
22
+
│laptop │ │wsl │ │rpi │ copies in secrets/
23
+
└─────────┘ └──────┬──────┘ └────────┬─────┘
24
+
│ │
25
+
(disabled— (disabled—
26
+
FIXME pubkey) FIXME pubkey)
24
27
```
28
+
29
+
> **Note**: Minimal hosts (`kats-wsl`, `kats-rpi`) currently have secrets **disabled** — their `age.rekey.hostPubkey` is set to a placeholder (`# FIXME: replace with actual host pubkey`) and the `gitKey` secret has `enable = false`. To enable secrets on these hosts, get their actual SSH host pubkey, update `age.rekey.hostPubkey`, remove the `enable = false`, and run `agenix rekey -a`.
25
30
26
31
- **Source secrets** live in their aspect folder (e.g. `modules/aspects/programs/git/gitKey.age`)
27
32
- Encrypted with your **master identity** (`~/.config/agenix/identity.txt`, converted from `~/.ssh/id_ed25519`)
+19
to-kat/the-den-framework.md
+19
to-kat/the-den-framework.md
···
65
65
den.batteries.hostname # auto-detect hostname
66
66
(den.batteries.define-user { }) # auto-create user skeletons
67
67
];
68
+
69
+
den.default.nixos.home-manager.backupFileExtension = "bk";
70
+
68
71
den.schema.user.classes = lib.mkDefault [ "homeManager" ];
69
72
```
73
+
74
+
The `nixos` section of `den.default` applies to every host. Notably `home-manager.backupFileExtension = "bk"` prevents activation failures when home-manager would overwrite existing user dotfiles — the old file gets renamed with a `.bk` extension instead.
70
75
71
76
### `den.batteries`
72
77
···
74
79
75
80
- **`den.batteries.hostname`** — Automatically sets `networking.hostName` based on the host's entity name. No need to manually set hostname in each host config.
76
81
- **`den.batteries.define-user`** — Auto-creates user entries (`users.users.<name>.isNormalUser = true`) for every user declared in `hosts/default.nix`. With `{ }` (empty args), it uses defaults.
82
+
83
+
### `den.schema.user.includes`
84
+
85
+
Controls which aspects are included for every user automatically. Set in `dendritic.nix`:
86
+
87
+
```nix
88
+
den.schema.user.includes = [ den._.mutual-provider ];
89
+
```
90
+
91
+
This enables the **mutual-provider** battery, which lets host aspects deliver config to their users (and vice versa) without the user aspect needing to explicitly include program aspects.
92
+
93
+
**Result**: A host aspect can use `provides.to-users` or `provides.<username>` to forward `homeManager` config to specific users. For example, `den.aspects.kats-laptop.provides.ksakura.includes = [ den.aspects.cli ]` delivers helix's home-manager config to ksakura without the user aspect including it.
94
+
95
+
**Why this exists**: Program aspects define their home-manager config under `den.aspects.programs.<name>.homeManager`, but the den system only forwards `homeManager` sections to users when the user aspect (or an aspect in its include chain) contains them. The mutual-provider battery bridges this gap by allowing the host aspect to "provide" config to its users.
77
96
78
97
### `den.schema.user.classes`
79
98