Files
m3ta-home/docs/superpowers/specs/2026-11-02-t3code-nixos-module-design.md
T
m3ta-chironandClaude Opus 5.5 2187d9263d feat(t3code): add environmentFile option
Loads an optional KEY=value file (e.g. an agenix secret) as the
service's systemd EnvironmentFile. Store paths are rejected so secrets
cannot end up in the Nix store.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 07:48:18 +01:00

9.7 KiB

T3 Code als NixOS-Modul in m3ta-home

Ziel

Der T3-Code-Server wird einmal in m3ta-home definiert statt pro Host. Er läuft auf m3-kratos (nixos-config) und AZ-LT-NIX (AZ-NIX-CLIENTS) und ist nur aus dem gerade aktiven NetBird-Netz erreichbar. Zwischen privatem und Firmen-Control-Server wird zur Laufzeit per NetBird-Profil gewechselt, ohne Rebuild. Von T3 gestartete Agents committen auf beiden Hosts als m3ta-chiron.

Erfolgskriterien

  1. Beide Hosts bauen mit m3ta.t3code.enable = true; pro Host sind nur enable und user nötig.
  2. Nach netbird up --profile <name> lauscht T3 Code auf der neuen NetBird-IP, ohne manuellen Eingriff.
  3. Der Port ist nur über wt0 offen, und der Server bindet nie an eine andere Adresse.
  4. Ein Commit aus einer T3-Session auf AZ-LT-NIX hat m3ta-chiron als Author und Committer.
  5. Pushes aus einer T3-Session nach code.m3ta.dev und git.az-gruppe.com nutzen ~/.ssh/m3ta-chiron.
  6. Tea nutzt in Repos beider Instanzen den passenden Token.

Nicht im Umfang

  • m3-hermes behält seinen Dienst und seine Agent-Runtime. Der Host bekommt nur das Overlay aus der neuen Quelle.
  • Beide NetBird-Netze gleichzeitig (services.netbird.clients).
  • Deklarative NetBird-Profile: Sie enthalten die Peer-Registrierung und bleiben imperativ.
  • Die übrige NetBird-Konfiguration der Hosts.

Modul

modules/nixos/t3code.nix, exportiert als nixosModules.t3code.

Option Typ Default
m3ta.t3code.enable bool false
m3ta.t3code.user str keiner (Pflichtfeld)
m3ta.t3code.port port 3773
m3ta.t3code.interface str "wt0"
m3ta.t3code.package package pkgs.llm-agents.t3code
m3ta.t3code.environmentFile null oder absoluter Pfad außerhalb des Stores null

Eine Assertion verlangt services.netbird.enable = true.

systemd.services.t3code:

  • Läuft als user mit Gruppe users; HOME und WorkingDirectory kommen aus config.users.users.<user>.home.
  • T3CODE_PORT kommt aus port.
  • environmentFile wird, falls gesetzt, als EnvironmentFile geladen (KEY=value-Zeilen, z. B. ein agenix-Secret).
  • path enthält /etc/profiles/per-user/<user> und /run/current-system/sw.
  • Restart = "on-failure", RestartSec = 5.
  • bindsTo, after und wantedBy zeigen auf sys-subsystem-net-devices-<interface>.device.
  • after enthält zusätzlich netbird.service.

Das Startskript wartet auf die IPv4-Adresse des Interface und führt dann t3 serve --host <ip> per exec aus. Kommt innerhalb von 60 Sekunden keine Adresse, beendet es sich mit Fehler und Restart versucht es erneut.

Die Firewall öffnet networking.firewall.interfaces.<interface>.allowedTCPPorts = [port].

Der Import steht in hosts/common beider Repos, enable und user in der Host-Konfiguration.

Profilwechsel

Die Profile werden einmal pro Host angelegt:

netbird profile add private
netbird up --profile private --management-url https://<privater-server>

Danach genügt netbird up --profile <name>. Das Profil default ist auf AZ-LT-NIX der Firmen-Server. wt0 verschwindet beim Wechsel und entsteht neu, dadurch startet der Dienst über die Device-Unit neu.

Bestätigt am 2026-11-02 auf AZ-LT-NIX: Wechsel zwischen den Netzen über den NetBird-Client funktioniert, T3 Code folgt ohne Eingriff. Ein Watcher für Adressänderungen ist nicht nötig.

T3-Clients brauchen pro Netz einen eigenen Eintrag und müssen im selben Netz sein. Ob pro Adresse neu gepairt werden muss, wird beim Rollout geprüft.

Agent-Identität

Das Overlay t3code-agent-identity wandert aus nixos-config/overlays/default.nix nach m3ta-home und wird als overlays.t3code-agent-identity zusätzlich zu den m3ta-nixpkgs-Overlays exportiert. Beide Repos binden es nach llm-agents.overlays.shared-nixpkgs ein, AZ-NIX-CLIENTS zusätzlich nach llm-agents-overrides. Es umhüllt t3code und t3code-desktop, also gilt die Identität auch für die Desktop-App.

Die Identität gilt nur für Prozesse, die T3 startet. Die globale Git-Konfiguration auf AZ-LT-NIX bleibt Sascha König. Author und Committer gelten für jedes Remote.

Mehrere Gitea-Instanzen

m3ta-chiron existiert auf zwei Instanzen, jede mit eigenem Token. Das Overlay bekommt dafür eine Instanzliste statt der festen Werte für code.m3ta.dev:

Name URL SSH Token-Datei
m3ta https://code.m3ta.dev gitea@code.m3ta.dev:22 /run/agenix/agent-gitea-token-m3ta
az https://git.az-gruppe.com gitea@git.az-gruppe.com:2022 /run/agenix/agent-gitea-token-az

Daraus erzeugt das Overlay:

  • tea: Der Wrapper schreibt pro lesbarer Token-Datei einen Login. Tea wählt den Login selbst anhand des Hosts im Git-Remote (MatchLogins), der Token geht also nur an seine Instanz. Fehlt eine Datei, entfällt nur dieser Login. default: true trägt der erste erzeugte Login.
  • SSH: Pro Instanz ein Host-Block mit User gitea, Port, IdentityFile ~/.ssh/m3ta-chiron und IdentitiesOnly yes. Alle anderen Hosts nutzen weiter ~/.ssh/config.
  • Known Hosts: Die Host-Keys beider Instanzen, für git.az-gruppe.com als [git.az-gruppe.com]:2022.

Eine Instanz, die nicht in der Liste steht, bekommt weder SSH-Einstellungen noch Token.

Beide Accounts nutzen denselben Schlüssel ~/.ssh/m3ta-chiron pro Host.

Secrets

Pro Instanz gibt es eine eigene Datei, damit sich Tokens einzeln rotieren lassen und der Arbeits-Token nur auf den Hosts liegt, die ihn brauchen.

Repo Datei publicKeys Hosts
AZ-NIX-CLIENTS secrets/agent-gitea-token-m3ta.age [AZ-LT-NIX sascha.koenig] AZ-LT-NIX
AZ-NIX-CLIENTS secrets/agent-gitea-token-az.age [AZ-LT-NIX sascha.koenig] AZ-LT-NIX
nixos-config secrets/agent-gitea-token-m3ta.age wie bisher hermes-gitea-token m3-kratos, m3-hermes
nixos-config secrets/agent-gitea-token-az.age [m3-kratos] ++ users m3-kratos

m3-hermes bekommt den Arbeits-Token nicht.

In nixos-config ersetzt die neue Datei hermes-gitea-token.age; der Inhalt bleibt gleich. Alle Tokens gehören dem Account m3ta-chiron der jeweiligen Instanz.

Voraussetzungen

Was Wie Durch
~/.ssh/m3ta-chiron auf AZ-LT-NIX ssh-keygen -t ed25519 -N "" -C chiron-t3-az-lt-nix -f ~/.ssh/m3ta-chiron Sascha
~/.ssh/m3ta-chiron auf m3-kratos Vorhandenen Schlüssel prüfen, sonst wie oben mit -C chiron-t3-m3-kratos anlegen Sascha
Public Keys Beide Hosts beim Account m3ta-chiron auf beiden Instanzen eintragen Sascha
Erreichbarkeit Von m3-kratos ssh -T -p 2022 gitea@git.az-gruppe.com testen Sascha
Tokens und .age-Dateien Pro Instanz einen Token erzeugen und mit agenix -e verschlüsseln Sascha
agenix-Einträge in den Host-secrets.nix Owner ist der jeweilige T3-User Implementierung

Korrektur an coding.agents.gitIdentity

profiles/sets/coding/agents/agents.nix setzt sshKey fest auf /home/m3tam3re/.ssh/gitea. Auf AZ-LT-NIX steht dieser Pfad deshalb schon heute in GIT_SSH_COMMAND in hm-session-vars.sh, obwohl die Datei dort nicht existiert.

  • agents.nix setzt den Wert per lib.mkDefault.
  • AZ-LT-NIX setzt coding.agents.gitIdentity.sshKey = "/home/sascha.koenig/.ssh/m3ta-chiron".

Dieselbe gitIdentity exportiert GIT_AUTHOR_* und GIT_SSH_COMMAND für alle Shells, die hm-session-vars.sh laden. In Nushell sind die Variablen nicht gesetzt. In Shells, die die Datei laden, committet und pusht auf AZ-LT-NIX also auch manuelles Git als m3ta-chiron. Dieses Verhalten bleibt unverändert.

Änderungen pro Repo

m3ta-home

  • Neu: modules/nixos/t3code.nix
  • flake.nix: Outputs nixosModules.t3code und overlays.t3code-agent-identity
  • agents.nix: sshKey per mkDefault

nixos-config

  • Flake-Input m3ta-home aktualisieren, Modul und Overlay aus m3ta-home einbinden
  • Lokales Overlay und hosts/m3-kratos/services/t3code.nix entfernen
  • m3-kratos: m3ta.t3code = { enable = true; user = "m3tam3re"; port = config.m3ta.ports.get "t3code"; };
  • hermes-gitea-token durch agent-gitea-token-m3ta ersetzen (secrets.nix, m3-kratos, m3-hermes)
  • agent-gitea-token-az ergänzen (secrets.nix, m3-kratos)

AZ-NIX-CLIENTS

  • Flake-Input m3ta-home aktualisieren, Modul und Overlay einbinden
  • t3code = 3773 in hosts/common/ports.nix
  • AZ-LT-NIX: m3ta.t3code, gitIdentity.sshKey, beide Secret-Einträge
  • secrets.nix: Einträge für beide Tokens

Der lokale nixos-config-Klon ist 112 Commits hinter origin/master und hat eine lokale Änderung an secrets/rustfs-secret-key.age. Die Arbeit dort startet in einem eigenen Worktree auf Basis von origin/master.

Reihenfolge

  1. Prüfung des wt0-Verhaltens durch Sascha, weil die Firmenverbindung dabei kurz wegfällt.
  2. m3ta-home implementieren.
  3. Beide Hosts mit --override-input m3ta-home path:… bauen, ohne switch.
  4. Schlüssel und Secret für AZ-LT-NIX anlegen (siehe Voraussetzungen).
  5. Deployment auf AZ-LT-NIX, dann m3-kratos.

Fehlerfälle

  • Keine Adresse auf wt0: Das Startskript scheitert nach 60 Sekunden, systemd versucht es erneut.
  • NetBird getrennt: Der Dienst stoppt mit wt0 und startet nur mit wt0 wieder. T3 Code ist dann offline, aber nie außerhalb des Mesh erreichbar.
  • Schlüssel fehlt: Der Push zu einer der beiden Instanzen scheitert, es gibt keinen Rückfall auf einen persönlichen Schlüssel.
  • Token fehlt: T3 erkennt die betroffene Instanz nicht als Gitea. Commits und Pushes funktionieren weiter, Change Requests nicht. Die andere Instanz ist nicht betroffen.

Prüfung

  • nix eval und nixos-rebuild build für AZ-LT-NIX und m3-kratos.
  • Nach dem Deployment: Kriterien 2 bis 6, je Profil mit ss -ltnp, je Instanz mit einem Testcommit und tea repos.