10 KiB
T3 Code als NixOS-Modul: Implementierungsplan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: T3 Code läuft aus einem Modul in m3ta-home auf m3-kratos und AZ-LT-NIX, folgt dem aktiven NetBird-Profil, und T3-Agents arbeiten auf beiden Gitea-Instanzen als m3ta-chiron.
Architecture: m3ta-home exportiert nixosModules.t3code und overlays.t3code-agent-identity. nixos-config und AZ-NIX-CLIENTS binden beides ein und liefern pro Host nur enable, user, port und Secrets.
Tech Stack: Nix Flakes, NixOS-Module, systemd, agenix, tea, NetBird 0.81.
Spec: docs/superpowers/specs/2026-11-02-t3code-nixos-module-design.md
Global Constraints
- Secret-Pfade:
/run/agenix/agent-gitea-token-m3taund/run/agenix/agent-gitea-token-az. - Instanzen:
m3ta=https://code.m3ta.dev, SSH-Port 22;az=https://git.az-gruppe.com, SSH-Port 2022; SSH-User jeweilsgitea. - Identität:
m3ta-chiron/m3ta-chiron@agentmail.to; Schlüssel~/.ssh/m3ta-chiron. - Host-Keys:
code.m3ta.dev ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFmmqZ4GgDEXJgj8uYrZAr/EoLIA6LJGkTIyKGQD/60aund[git.az-gruppe.com]:2022 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIItSijmU5YwcJcoshtmYxpxBaVA4TPaCMk23ws7KDkAH. - Port-Default
3773; Interface-Defaultwt0. - Kein
switch, kein Push und kein Merge ohne ausdrückliche Freigabe. Arbeit in jedem Repo auf dem Branchfeat/t3code-module. nixos-confignur in einem Worktree auf Basis vonorigin/masterändern;secrets/rustfs-secret-key.ageim Hauptcheckout bleibt unberührt.- Tokens nie in Logs, Testausgaben oder den Nix-Store.
Review Focus
wt0ist beim Dienststart da, hat aber noch keine IPv4: Das Skript wartet höchstens 60 Sekunden und bindet nie an0.0.0.0(Test Task 1).- Nur ein Token ist lesbar: Genau dieser Login wird erzeugt und trägt
default: true(Test Task 2). - Kein Token ist lesbar:
tealäuft ohne Login weiter, ohne Abbruch im Wrapper (Test Task 2). userfehlt oder NetBird ist aus: Die Evaluation scheitert mit klarer Meldung statt zur Laufzeit (Test Task 1).- Git-Remote auf
git.az-gruppe.com: SSH nutzt Port 2022 undm3ta-chiron, andere Hosts weiter~/.ssh/config(Test Task 2).
Task 0: Voraussetzungen durch Sascha
Nicht durch Agents ausführbar. Task 1 hängt nur an Schritt 1, Task 4 und 5 auch an den Secrets.
- Step 1:
wt0-Verhalten prüfen. Zweites Profil anlegen, wechseln undip monitor link dev wt0beobachten. Erwartet:wt0verschwindet und entsteht neu. Sonst bekommt Task 1 den in der Spec genanntenip monitor-Watcher. - Step 2: Schlüssel und Tokens. Tabelle „Voraussetzungen“ der Spec abarbeiten.
- Step 3:
.age-Dateien laut Tabelle „Secrets“ der Spec erzeugen, nachdem Task 4 und 5 diesecrets.nix-Einträge ergänzt haben.
Task 1: NixOS-Modul
Files:
- Create:
modules/nixos/t3code.nix - Create:
modules/nixos/t3code.test.sh - Modify:
flake.nix
Interfaces:
-
Produces:
nixosModules.t3codemit den Optionenm3ta.t3code.{enable,user,port,interface,package}aus der Spec. -
Step 1: Test schreiben.
t3code.test.shevaluiert das Modul pernixpkgs.lib.nixosSystemmit einem Stub-llm-agents.t3code(Stil wieprofiles/sets/coding/agents/ai-memory.test.sh) und prüft:bindsToundwantedByenthaltensys-subsystem-net-devices-wt0.deviceserviceConfig.Useristalice,environment.T3CODE_PORTist"3773",HOMEist/home/alicenetworking.firewall.interfaces.wt0.allowedTCPPortsist[3773]- ohne
services.netbird.enablescheitert der Build vonsystem.build.toplevelmitm3ta.t3code requires services.netbird.enable - ohne
userscheitert die Evaluation enable = falseerzeugt keinen Dienst
-
Step 2: Startskript-Test ergänzen. Das Skript mit einem Stub für
ipundt3starten. Liefert der Stub sofort eine Adresse, ist dert3-Aufrufserve --host 100.1.2.3. Liefert er keine, endet das Skript mit Exit 1 (Timeout im Test perT3CODE_ADDR_TIMEOUT=1, Default60) und ruftt3nicht auf. -
Step 3: Test ausführen.
bash modules/nixos/t3code.test.sh; erwartet: FAIL, weil das Modul fehlt. -
Step 4: Modul schreiben laut Abschnitt „Modul“ der Spec. Startskript per
pkgs.writeShellApplication, Adresse perip -4 -o addr show dev <interface>, Aufruf mitexec. Inflake.nix:nixosModules.t3code = ./modules/nixos/t3code.nix. -
Step 5: Test ausführen. Erwartet: PASS.
-
Step 6: Commit
feat(t3code): add NixOS module bound to the NetBird interface.
Task 2: Identitäts-Overlay mit zwei Instanzen
Files:
- Create:
overlays/t3code-agent-identity.nix - Create:
overlays/t3code-agent-identity.test.sh - Modify:
flake.nix
Interfaces:
-
Produces:
overlays.t3code-agent-identity. Die Datei ist{tokenFiles ? {}}: final: prev: {…}; die Instanzliste steht in der Datei,tokenFilesüberschreibt Token-Pfade pro Instanzname (für Tests). Der Flake exportiert die Standardanwendung und behältinputs.m3ta-nixpkgs.overlaysper//. -
Step 1: Test schreiben. Overlay mit Test-Instanzen und temporären Token-Dateien anwenden, gegen einen Stub-
llm-agents.t3codebauen und prüfen:- beide Tokens lesbar:
tea loginslistetm3taundazmit ihren URLs - nur
azlesbar: nuraz, mitdefault: true - keiner lesbar:
tea loginsendet mit Exit 0 und leerer Liste - ein gefälschtes Token taucht nach dem Lauf nirgends unter
$TMPDIRauf (Temp-Verzeichnis aufgeräumt) und nicht im Closure (nix-store -qR+grep) ssh -F <config> -G git.az-gruppe.com:port 2022,user gitea,identityfile ~/.ssh/m3ta-chironssh -F <config> -G code.m3ta.dev:port 22,user gitea, gleicher Schlüsselssh -F <config> -G example.orgmit Test-HOMEund eigener~/.ssh/config: nutzt deren Werte, keinm3ta-chiron- im Wrapper sind
GIT_AUTHOR_NAMEundGIT_COMMITTER_NAMEm3ta-chiron
- beide Tokens lesbar:
-
Step 2: Test ausführen. Erwartet: FAIL.
-
Step 3: Overlay schreiben. Aus
git show origin/master:overlays/default.nixinnixos-configübernehmen (t3code-agent-identity) und nur die festen Werte durchinstancesersetzen. Der Rest-Block wirdHost * !code.m3ta.dev !git.az-gruppe.com, ausinstanceserzeugt. Beibehalten: privates Temp-Verzeichnis pro Aufruf und der Kommentar zumIdentityFile-Verhalten. -
Step 4: Test ausführen. Erwartet: PASS.
-
Step 5: Commit
feat(t3code): move agent identity overlay here, support two Gitea instances.
Task 3: gitIdentity.sshKey überschreibbar
Files:
-
Modify:
profiles/sets/coding/agents/agents.nix:16 -
Step 1: Ändern.
sshKey = lib.mkDefault "/home/m3tam3re/.ssh/gitea",libin die Modulargumente aufnehmen. -
Step 2: Prüfen. Aus AZ-NIX-CLIENTS:
nix eval --raw --override-input m3ta-home path:<m3ta-home> .#nixosConfigurations.AZ-LT-NIX.config.home-manager.users."sascha.koenig".coding.agents.gitIdentity.sshKey. Erwartet:/home/m3tam3re/.ssh/gitea, also unverändert ohne Override. -
Step 3: Commit
fix(agents): let hosts override the agent SSH key path.
Task 4: AZ-NIX-CLIENTS einbinden
Files (Repo AZ-NIX-CLIENTS):
- Modify:
hosts/common/default.nix(Overlay nachllm-agents-overrides, Modul-Import) - Modify:
hosts/common/ports.nix(t3code = 3773) - Modify:
hosts/common/users/sascha.koenig.nix(coding.agents.gitIdentity.sshKey = "/home/sascha.koenig/.ssh/m3ta-chiron"in den AZ-LT-NIX-Flags) - Modify:
hosts/AZ-LT-NIX/services/default.nixoder neueservices/t3code.nix(m3ta.t3code) - Modify:
hosts/AZ-LT-NIX/secrets.nix,secrets.nix
Interfaces:
-
Consumes:
nixosModules.t3code,overlays.t3code-agent-identity. -
Step 1: Änderungen ohne Secrets einbauen.
m3ta.t3code = { enable = true; user = "sascha.koenig"; port = config.m3ta.ports.get "t3code"; }; -
Step 2: Bauen.
nixos-rebuild build --flake .#AZ-LT-NIX --override-input m3ta-home path:<m3ta-home>; erwartet: Erfolg. -
Step 3: Werte prüfen. Per
nix eval:systemd.services.t3code.serviceConfig.Useristsascha.koenig,gitIdentity.sshKeyist der neue Pfad. -
Step 4: Thin Client prüfen.
nix eval .#nixosConfigurations.AZ-TC-01.config.systemd.services.t3code.enablemit Override: Fehler oder fehlender Dienst; der Host bekommt keinen T3-Dienst. -
Step 5: Commit
feat(AZ-LT-NIX): run T3 Code from the m3ta-home module. -
Step 6: Secret-Einträge ergänzen, sobald Saschas
.age-Dateien da sind (Rezept:publicKeysaus der Spec), bauen, Commitfeat(AZ-LT-NIX): add agent Gitea tokens.
Task 5: nixos-config umstellen
Files (Repo nixos-config, Worktree auf origin/master):
- Modify:
hosts/common/default.nix,overlays/default.nix(lokales Overlay entfernen, das aus m3ta-home einbinden, Modul-Import) - Delete:
hosts/m3-kratos/services/t3code.nix - Modify:
hosts/m3-kratos/services/default.nix,hosts/m3-kratos/secrets.nix,hosts/m3-hermes/secrets.nix,hosts/m3-hermes/services/t3code.nix(Kommentar zum Secret-Namen),secrets.nix
Interfaces:
-
Consumes: wie Task 4.
-
Step 1: Worktree anlegen und Modul sowie Overlay einbinden. Für m3-kratos:
m3ta.t3codelaut Spec. -
Step 2: Bauen. m3-kratos und m3-hermes mit
--override-input m3ta-home path:<m3ta-home>; erwartet: Erfolg. -
Step 3: Prüfen. m3-hermes-
ExecStartenthält weiter--host 0.0.0.0. m3-kratos-ExecStartenthält keine feste IP mehr. -
Step 4: Commit
refactor(m3-kratos): use the T3 Code module from m3ta-home. -
Step 5: Secrets umstellen, sobald Saschas
.age-Dateien da sind:hermes-gitea-tokendurchagent-gitea-token-m3taersetzen,agent-gitea-token-aznur auf m3-kratos.git grep hermes-gitea-tokenist danach leer. Bauen, Commitrefactor(secrets): rename agent Gitea tokens per instance.
Task 6: Abschluss und Rollout
Pushes, Lock-Updates und switch nur nach ausdrücklicher Freigabe.
- Step 1: m3ta-home mergen und pushen, in beiden Repos
nix flake update m3ta-home, ohne Override erneut bauen. - Step 2: Deployment auf AZ-LT-NIX, dann m3-kratos; m3-hermes erhält nur den Secret-Wechsel.
- Step 3: Kriterien 2 bis 6 der Spec prüfen. Je Profil
ss -ltnp | grep 3773zeigt die aktuelle NetBird-IP. Je Instanz ein Testcommit aus einer T3-Session (git log -1 --format='%an %cn'), Push undtea repos. Pairing pro Netz prüfen und das Ergebnis in die Spec schreiben.