mission-control-v2/AGENTS.md

AGENTS.md — Homelab Orchestrator (vormals Mission Control 2.0)

Projekt-Geschmack für Coding-Agenten (Kilo Code, Claude Code lesen diese Datei). Kurz gehalten, nur die Wahrheiten, die man sonst schmerzhaft lernt. Details: README.md, docs/.

Was das ist

Lokaler Local-AI-Stack für die Box (Bosgame M5, Strix Halo, Vulkan/RADV). Schichten: Engine (llama-swap) · Builtin-Routing-Gateway (model: auto) · MC2 (FastAPI + React/shadcn) · Hermes-Agent (das autonome Gehirn "Lucy"). Backend Python (Box läuft Python 3.14), Frontend Vite/React/shadcn/Tailwind.

Hardware-Spezifikationen der Box (WICHTIG für alle Agenten):

• System: Bosgame M5 (AMD Strix Halo APU)
• Arbeitsspeicher (RAM/VRAM): 128 GB Shared Memory (ca. 122.7 GB nutzbar).
• Inference-Limit: Modelle im GGUF-Format dürfen maximal ca. 100-110 GB groß sein (entspricht ca. 150B Parametern bei Q4_K_M). Größere Modelle (wie 200B+ oder 2T Parameter) können lokal nicht ausgeführt werden und sind auszuschließen, es sei denn, es handelt sich um stark quantisierte MoEs. Gedächtnis & Dienste: Hermes ist das autonome Agenten-Gehirn („Lucy") und die alleinige Gedächtnis-Wahrheit — es führt sein Gedächtnis selbst. Der frühere Sidecar auf :8765 samt Memory-MCP-Server und MC2-Memory-Plugin wurde am 07.08.2026 abgelöst und am 27.08.2026 restlos ausgebaut (docs/wissen/VERDIKTE.md): MC2 hat keine /api/memory-Routen mehr, nichts darf mehr dorthin greifen. Governor, Zed-Workflows und alte Mittelschichten sind komplett gelöscht.

Sprache (nicht verhandelbar)

• Alles User-Sichtbare ist Deutsch: UI-Texte, Fehlermeldungen, Update-/Radar-Meldungen, Skills, LLM-Summaries, Commit-Messages, Code-Kommentare.
• Hermes' INTERNE System-Prompts bleiben Englisch (fremde Software, wir forken sie nicht). Antwort-Sprache ≠ Prompt-Sprache — Deutsch kommt aus SOUL.md, nicht aus den Tool-Prompts.

Build & Deploy (die häufigste Falle)

• frontend/dist WIRD committet. Auf der Box läuft KEIN Node-Build; das Backend liefert die gebauten Assets direkt aus. Nach jeder Frontend-Änderung: cd frontend && npm run build, dann das neue frontend/dist mit-committen. Vergessen = Box zeigt alten Stand.
• Deploy (bash ~/mission-control-v2/deploy/deploy.sh auf der Box) holt origin/main per fast-forward — main muss vorher auf Gitea liegen, im Box-Checkout nie von Hand ändern. Zweistufig seit 24.09.2026: Stufe 1 holt den Stand und startet die NEUE Fassung des Skripts, Stufe 2 prüft (pruefen.sh), spielt Units/Cron-Skripte/Skills aus, startet neu und prüft nach. Scheitert etwas: automatisch zurück auf den alten Stand + dringende Meldung. Laufende Update-Jobs verschieben den Deploy. Die llama-swap-Config wird nur überschrieben, wenn sich der Repo-Abzug im selben Deploy geändert hat (sonst gewinnt die lebende Datei, die MC2 selbst schreibt).
• Nie direkt auf main arbeiten. Immer Branch (wartung/...), Gate grün, dann Merge/Deploy.

Agentic IDE & Vibe Coding

• Zero Middle-Layers: Coding passiert zu 100% lokal auf dem Dev-PC in OpenChamber (mit eigener OpenCode-CLI).
• Es gibt keinen Zed-Workflow, keine OpenCode-CLI-Mittelschicht und keinen Governor mehr.
• Der Agent in OpenChamber nutzt die Modelle der Box über http://192.168.178.151:9001/v1 (Provider aibox, nur Rollen-Aliase; Vorlage der PC-Config: deploy/opencode-config/).
• Prüftor: bash deploy/pruefen.sh (Shell-/Python-Syntax, ruff, Importe, pytest) muss vor jedem Push grün sein. Der Deploy auf der Box führt es vor dem Umschalten noch einmal aus; rot = automatisch zurück auf den alten Stand.

Zeit & Umgebung

• Box = Ubuntu, läuft in Europe/Berlin (seit 03.07.2026; vorher UTC). Dev-PC = Windows. Naive/lokale Zeiten immer über MC_LOCAL_TZ (= Europe/Berlin) auflösen, nie datetime.now() ohne TZ annehmen (siehe backend/services/reminders.py).

Backend-Konventionen

• Router unter backend/routers/ (APIRouter(prefix="/api")), Logik in backend/services/ (Single Source of Truth — Router bleiben dünn). Beispiel-Lehre: Restart-Allowlist lebt NUR in services.maintenance (System-Dienste via sudo -n, User-Dienste via systemctl --user); keine zweite Allowlist in einem Router duplizieren.
• Gate vor Commit: bash deploy/pruefen.sh (enthält py_compile, ruff check . und die Tests).
• Wartung ist sudo-frei gedacht (systemctl --user). Wo doch sudo nötig ist (llama-swap = System-Dienst), sauber über die NOPASSWD-Whitelist / password_required-Rückgabe, nie hart failen.
• ‼️ Die feingranularen sudoers.d-Regeln sind faktisch wirkungslos. In /etc/sudoers steht hitonabi ALL=(ALL) NOPASSWD: ALL — der Nutzer, unter dem alle MC2-Dienste laufen, darf ohnehin alles passwortlos. sudoers.d/mc2-autonomie und sudoers.d/mission-control dokumentieren also, was gebraucht würde, schränken aber nichts ein. Das ist eine bewusste Entscheidung für die Single-User-Appliance; verlasse dich beim Bauen nicht darauf, dass eine Whitelist dich bremst. Wer das wirklich härten will, kommt um einen eigenen Service-User nicht herum — die Pauschalzeile einfach zu ziehen, bricht OS-Update, Config-Sync und den wöchentlichen Auto-Neustart still. (Geprüft 27.08.2026; die doppelte Zeile wurde damals entfernt, Sicherung /root/sudoers.bak-*.)
• Lokal (Windows) müssen Box-Shell-Befehle harmlos fehlschlagen statt zu crashen.

Grenzen (Verdikt, eingehalten)

• Hermes-Quellcode nie selbst patchen (Fork verboten). Config/Deps ja, Code-Umbau nein.
• Security-Config (approvals, Tokens, ufw, command_allowlist) nie ohne explizites User-Ja.
• Alles reversibel halten: Branch + Backup + Pin.

Gitea

Remote = ssh://gitea@192.168.178.153:2222/Hitonabi/mission-control-v2.git (SSH, Push aus Git-Bash geht). Bei Aussetzern Push mit Retry. Neue Repos per API anlegen. Kein GitHub. Ungemergtes, das weg soll, erst als Tag archiv/<name> sichern, dann löschen.