Files
m3ta-home/docs/superpowers/plans/2026-11-02-t3code-nixos-module.md
2026-11-02 08:00:24 +01:00

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-m3ta und /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 jeweils gitea.
  • Identität: m3ta-chiron / m3ta-chiron@agentmail.to; Schlüssel ~/.ssh/m3ta-chiron.
  • Host-Keys: code.m3ta.dev ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFmmqZ4GgDEXJgj8uYrZAr/EoLIA6LJGkTIyKGQD/60a und [git.az-gruppe.com]:2022 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIItSijmU5YwcJcoshtmYxpxBaVA4TPaCMk23ws7KDkAH.
  • Port-Default 3773; Interface-Default wt0.
  • Kein switch, kein Push und kein Merge ohne ausdrückliche Freigabe. Arbeit in jedem Repo auf dem Branch feat/t3code-module.
  • nixos-config nur in einem Worktree auf Basis von origin/master ändern; secrets/rustfs-secret-key.age im Hauptcheckout bleibt unberührt.
  • Tokens nie in Logs, Testausgaben oder den Nix-Store.

Review Focus

  • wt0 ist beim Dienststart da, hat aber noch keine IPv4: Das Skript wartet höchstens 60 Sekunden und bindet nie an 0.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: tea läuft ohne Login weiter, ohne Abbruch im Wrapper (Test Task 2).
  • user fehlt 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 und m3ta-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 und ip monitor link dev wt0 beobachten. Erwartet: wt0 verschwindet und entsteht neu. Sonst bekommt Task 1 den in der Spec genannten ip 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 die secrets.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.t3code mit den Optionen m3ta.t3code.{enable,user,port,interface,package} aus der Spec.

  • Step 1: Test schreiben. t3code.test.sh evaluiert das Modul per nixpkgs.lib.nixosSystem mit einem Stub-llm-agents.t3code (Stil wie profiles/sets/coding/agents/ai-memory.test.sh) und prüft:

    • bindsTo und wantedBy enthalten sys-subsystem-net-devices-wt0.device
    • serviceConfig.User ist alice, environment.T3CODE_PORT ist "3773", HOME ist /home/alice
    • networking.firewall.interfaces.wt0.allowedTCPPorts ist [3773]
    • ohne services.netbird.enable scheitert der Build von system.build.toplevel mit m3ta.t3code requires services.netbird.enable
    • ohne user scheitert die Evaluation
    • enable = false erzeugt keinen Dienst
  • Step 2: Startskript-Test ergänzen. Das Skript mit einem Stub für ip und t3 starten. Liefert der Stub sofort eine Adresse, ist der t3-Aufruf serve --host 100.1.2.3. Liefert er keine, endet das Skript mit Exit 1 (Timeout im Test per T3CODE_ADDR_TIMEOUT=1, Default 60) und ruft t3 nicht 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 per ip -4 -o addr show dev <interface>, Aufruf mit exec. In flake.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ält inputs.m3ta-nixpkgs.overlays per //.

  • Step 1: Test schreiben. Overlay mit Test-Instanzen und temporären Token-Dateien anwenden, gegen einen Stub-llm-agents.t3code bauen und prüfen:

    • beide Tokens lesbar: tea logins listet m3ta und az mit ihren URLs
    • nur az lesbar: nur az, mit default: true
    • keiner lesbar: tea logins endet mit Exit 0 und leerer Liste
    • ein gefälschtes Token taucht nach dem Lauf nirgends unter $TMPDIR auf (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-chiron
    • ssh -F <config> -G code.m3ta.dev: port 22, user gitea, gleicher Schlüssel
    • ssh -F <config> -G example.org mit Test-HOME und eigener ~/.ssh/config: nutzt deren Werte, kein m3ta-chiron
    • im Wrapper sind GIT_AUTHOR_NAME und GIT_COMMITTER_NAME m3ta-chiron
  • Step 2: Test ausführen. Erwartet: FAIL.

  • Step 3: Overlay schreiben. Aus git show origin/master:overlays/default.nix in nixos-config übernehmen (t3code-agent-identity) und nur die festen Werte durch instances ersetzen. Der Rest-Block wird Host * !code.m3ta.dev !git.az-gruppe.com, aus instances erzeugt. Beibehalten: privates Temp-Verzeichnis pro Aufruf und der Kommentar zum IdentityFile-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", lib in 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 nach llm-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.nix oder neue services/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.User ist sascha.koenig, gitIdentity.sshKey ist der neue Pfad.

  • Step 4: Thin Client prüfen. nix eval .#nixosConfigurations.AZ-TC-01.config.systemd.services.t3code.enable mit 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: publicKeys aus der Spec), bauen, Commit feat(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.t3code laut 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-ExecStart enthält weiter --host 0.0.0.0. m3-kratos-ExecStart enthä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-token durch agent-gitea-token-m3ta ersetzen, agent-gitea-token-az nur auf m3-kratos. git grep hermes-gitea-token ist danach leer. Bauen, Commit refactor(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 3773 zeigt die aktuelle NetBird-IP. Je Instanz ein Testcommit aus einer T3-Session (git log -1 --format='%an %cn'), Push und tea repos. Pairing pro Netz prüfen und das Ergebnis in die Spec schreiben.