Lokale Claude-Code-fuer-Infrastruktur Plattform¶

AUDIT CONTEXT / HISTORICAL: Diese Roadmap beschreibt einen frueheren Entwicklungsstand. OpenCode wird inzwischen als AI Operations Console betrachtet, nicht primaer als Coding-Agent. Aktuelle Zielarchitektur siehe AI Operating System v1, Hermes Central Brain und OpenCode als AI Operations Console.

Stand: 2026-05-25

Ziel¶

Die bestehende Lanstyle AI-/Automation-Plattform soll evolutionaer zu einer lokalen, nachvollziehbaren und sicheren Agent-Runtime fuer Infrastrukturarbeit weiterentwickelt werden. OpenCode bleibt das bevorzugte Arbeits-Frontend. Bestehende Dienste werden erweitert, nicht ersetzt.

Leitbild:

OpenCode als primaeres Agent-Frontend
Ollama/DGX Spark als lokaler Modell-Host
Gitea/MkDocs als versionierte Wissens- und Dokumentationsquelle
NetBox als produktive IPAM/DCIM-Quelle
Vaultwarden als Secret-Quelle
n8n als Orchestrierungsschicht fuer wiederkehrende Workflows
MCP-first fuer Toolzugriffe
klare Approval-Flows fuer riskante Aktionen

Aktuelle Architektur¶

Vorhanden und weiterzuverwenden:

Bereich	Status	Rolle
OpenCode	vorhanden	primaeres Agent-Frontend fuer Infrastrukturarbeit
Open WebUI	vorhanden	Chat-/Knowledge-/Team-UI, nicht primaere Agent-Runtime
Ollama	vorhanden	lokaler Modell-Provider auf GB10/DGX Spark
Modelle	vorhanden	`gpt-oss:120b`, `qwen3-coder-next:latest`, weitere Coding-Modelle
Gitea	vorhanden	zentrale Repositories fuer Doku, Prompts, Runbooks, Skripte
MkDocs Material	vorhanden	menschlich lesbares Docs-as-Code-Frontend
NetBox	produktiv	Source of Truth fuer IPAM/DCIM
Vaultwarden	vorhanden	Secrets, Tokens, Passwoerter
SearXNG	vorhanden	interne Websuche fuer Open WebUI, spaeter optional OpenCode
n8n	vorhanden	Workflow-Orchestrierung, noch nicht final produktiv konfiguriert
Open Terminal	vorhanden	isolierte Tool-Ausfuehrung fuer Open WebUI
NPM	vorhanden	Reverse Proxy mit Access Lists

Bewertung¶

Die Grundarchitektur ist richtig ausgerichtet: Es gibt bereits getrennte Rollen fuer Modell-Hosting, Frontend, Secrets, Doku, IPAM und Orchestrierung. Der naechste Reifegrad entsteht nicht durch weitere Chat-UIs, sondern durch eine bessere Agent-Runtime-Schicht:

stabilere Tool-Schemas
zentrale MCP-Registry
reproduzierbare Toolserver
persistente Task-/Run-Historie
Review-/Approval-Flows
Logging und Tracing
klare Modell-Routing-Regeln
Knowledge-Pipeline aus Gitea, NetBox und MkDocs

OpenCode sollte deshalb nicht durch OpenHands oder Open WebUI ersetzt werden. OpenHands kann spaeter als isolierte Laufzeit fuer laengere Repo-/Code-Jobs evaluiert werden, aber nicht als neues Primaer-Frontend.

Hauptprobleme¶

1. Tool-Schema-Mismatch in OpenCode¶

Beobachtet wurden Modellaufrufe auf nicht vorhandene Tools wie list, run oder todo_write. OpenCode nutzt andere Toolnamen wie glob, grep, read, write, bash und todowrite.

Bewertung:

Das ist kein Infrastrukturproblem.
Es ist ein Alignment-Problem zwischen Modell, Systemprompt und Tool-Schema.
Workarounds ueber Alias-Tools wurden bereits getestet und wieder entfernt, weil sie lokale Plugin-Abhaengigkeiten kaputt gemacht haben.

Empfehlung:

Toolnamen in globalen OpenCode-Regeln weiter hart vorgeben.
Fuer Tool-intensive Jobs bevorzugt ein Modell nutzen, das OpenCode-Tools sauberer befolgt.
GPT-OSS 120B fuer Planung, Review, Architektur und lange Kontexte nutzen.
Qwen3-Coder-Next als Agent-/Tool-Modell nur behalten, wenn Toolaufrufe stabil sind.

2. Kein zentraler MCP-Hub¶

Aktuell sind MCPs punktuell angebunden, unter anderem Context7 und grep.app. Es fehlt eine interne Registry/Schicht, die MCPs versioniert, dokumentiert, healthcheckt und Berechtigungen zentral beschreibt.

Empfehlung:

MCPHub als zentrale Registry/Proxy-Schicht evaluieren.
FastMCP fuer eigene interne MCPs nutzen.
MCPs pro Risiko klassifizieren:
Read-only
Write-with-approval
Dangerous/manual-only

3. Secrets sind noch nicht Agent-native¶

Vaultwarden ist vorhanden, aber Agenten greifen nicht durchgaengig ueber eine definierte Secret-Abstraktion darauf zu.

Empfehlung:

Einen internen secrets-mcp oder secrets-helper bauen.
Standard: Secret nur per Name/Referenz abrufen, nie ausgeben.
Audit-Log fuer Secret-Zugriffe.
Kein Secret in Prompts, Git, Markdown oder Tool-Logs.

4. NetBox ist Source of Truth, aber noch nicht Agent-Workflow¶

NetBox ist produktiv und richtig positioniert. Es fehlt ein kontrollierter Agent-Zugriff fuer Lesen, Planen und optional Schreiben.

Empfehlung:

Dedizierten NetBox-Service-Token mit minimalen Rechten anlegen.
Zuerst read-only NetBox MCP.
Schreibende NetBox-Aktionen nur ueber Change-Plan und Approval.
NetBox-Exports regelmaessig nach Gitea/MkDocs spiegeln, ohne NetBox zu ersetzen.

5. n8n ist installiert, aber nicht produktiv orchestrierend¶

n8n ist sinnvoll, aber aktuell noch nicht die zentrale Automationsschicht.

Empfehlung:

n8n nur fuer klar begrenzte Workflows nutzen:
Gitea Push -> MkDocs Deploy pruefen
NetBox Webhook -> Wiki-Update-Task erstellen
Monitoring Alert -> OpenCode/Issue/Runbook verlinken
regelmaessige Inventar-Snapshots
Kein unkontrolliertes Ausfuehren von SSH-/PowerShell-Changes aus n8n.

6. Observability fehlt als Querschnitt¶

Aktuell gibt es Doku und Logs der einzelnen Dienste, aber keine zentrale Run-/Agenten-Telemetrie.

Empfehlung:

Minimal starten:
strukturierte Logs fuer MCPs
Request-ID pro Agent-Run
Git-Commit/Branch/Task-ID in Logs
zentraler Log-Zielort
Danach OpenTelemetry/Loki/Grafana evaluieren.

Zielarchitektur¶

flowchart LR
  User["Maximilian / Team"] --> OpenCode["OpenCode Desktop"]
  User --> OpenWebUI["Open WebUI"]

  OpenCode --> LLMRouter["LiteLLM / Modellrouter"]
  OpenWebUI --> LLMRouter
  LLMRouter --> Ollama["Ollama auf DGX Spark / GB10"]

  OpenCode --> MCPHub["MCPHub / MCP Registry"]
  MCPHub --> SSHMCP["SSH MCP"]
  MCPHub --> PSH["PowerShell MCP"]
  MCPHub --> NetBoxMCP["NetBox MCP"]
  MCPHub --> ProxmoxMCP["Proxmox MCP"]
  MCPHub --> GitMCP["Git/Gitea MCP"]
  MCPHub --> HTTPMCP["HTTP/OpenAPI MCP"]
  MCPHub --> DockerMCP["Docker MCP"]
  MCPHub --> BrowserMCP["Browser MCP"]
  MCPHub --> SecretsMCP["Vaultwarden Secret Helper"]

  GitMCP --> Gitea["Gitea"]
  NetBoxMCP --> NetBox["NetBox"]
  SecretsMCP --> Vault["Vaultwarden"]
  HTTPMCP --> APIs["NPM / M365 / UniFi / Dienste"]

  Gitea --> MkDocs["MkDocs Wiki"]
  n8n["n8n"] --> Gitea
  n8n --> NetBox
  n8n --> MkDocs

  Logs["Logging / Tracing"] --- MCPHub
  Logs --- LLMRouter
  Logs --- n8n

Modellrouting¶

Empfohlene Rollen:

Aufgabe	Modell	Begruendung
Architektur, Planung, Reviews, lange Analyse	`gpt-oss:120b`	Qualitaet vor Geschwindigkeit, gute Synthese
Tool-/Agentenarbeit, Codeaenderungen, Shell-nahe Aufgaben	`qwen3-coder-next:latest`	starkes Coding-/Agentenmodell, grosser Kontext
stabile Tool-lastige Fallback-Sessions	`qwen2.5-coder:32b`	bewahrter Fallback bei Tool-Schema-Problemen
schnelle Checks, kleine Edits	`qwen2.5-coder:7b`	schnell und guenstig lokal
Spezial-Reasoning	`deepseek-r1:70b` optional	nur falls Ressourcen und Antwortqualitaet den Betrieb rechtfertigen

LiteLLM ist sinnvoll, wenn:

OpenCode, Open WebUI und weitere Agenten einheitlich routen sollen
Modellnamen normalisiert werden sollen
Budgets, Logging und Fallbacks zentral konfiguriert werden sollen
spaeter externe Modelle kontrolliert angebunden werden sollen

LiteLLM sollte nicht eingefuehrt werden, wenn es nur ein weiterer Proxy ohne klare Routing-Regeln waere.

Context Management und Memory¶

Bestehende Quellen:

Gitea-Repositories
MkDocs Markdown
NetBox
OpenCode Memory
OpenCode Skills
Open WebUI Knowledge
lokale Projektordner

Naechster Reifegrad:

Gitea/MkDocs bleibt kanonische Textquelle.
NetBox bleibt kanonische Infrastrukturquelle.
Qdrant wird als Vektorindex fuer bereinigte Markdown-/Runbook-/Config-Daten genutzt.
PostgreSQL speichert Agent-Runs, Tasks, Entscheidungen und Approvals.
Neo4j/GraphRAG erst spaeter, wenn Abhaengigkeiten zwischen Kunden, Diensten, VLANs, Hosts und Changes wirklich graphbasiert abgefragt werden muessen.

LLMLingua2 kann spaeter fuer Kontextkompression getestet werden, aber erst nachdem die Quellen sauber strukturiert sind. Sonst komprimiert man nur unklare Daten.

Approval-Modell¶

Toolklassen:

Klasse	Beispiele	Verhalten
Read-only	`git status`, NetBox read, Proxmox list, DNS lookup	automatisch erlaubt
Local edit	Markdown, Skripte im Projektordner	erlaubt mit Backup und Diff
Controlled write	Gitea push, NetBox write, n8n workflow update	Plan + Diff + Approval
Risky infra	Proxmox VM/LXC Aenderung, UniFi Firewall, SSH system changes	explizite Freigabe pro Change
Dangerous	`rm -rf`, Firewall Default Policy, Secret-Export, Key-Kopie	standardmaessig blockieren

Jeder produktive Change braucht:

Ziel
Ist-Zustand
geplante Aenderung
betroffene Systeme
Backup
Rollback
Testplan
Commit/Run-ID

Priorisierte Roadmap¶

Phase 1: Stabilisierung¶

Ziel: Bestehendes Setup robust machen.

OpenCode-Regeln fuer Toolnamen und Arbeitsweise weiter schaerfen.
Modellrouting dokumentieren und OpenCode/Open WebUI konsistent setzen.
n8n initial fertigstellen:
Owner
NPM Proxy
SMTP Relay
Workflow-Export nach Git
NetBox read-only Token fuer Automationen anlegen.
Gitea/MkDocs Deploy und Backup pruefen.
IPv6-/DNS-Thema im LAN dauerhaft korrigieren.

Phase 2: MCP-Basis¶

Ziel: MCP-first statt einzelner Sonderintegrationen.

MCPHub evaluieren.
FastMCP-Template fuer interne MCPs erstellen.
Read-only MCPs bauen/anbinden:
NetBox
Proxmox
Gitea
HTTP/OpenAPI
Filesystem
Logging pro MCP-Aufruf einfuehren.
Tool-Rechte zentral dokumentieren.

Phase 3: Knowledge und Memory¶

Ziel: reproduzierbarer Kontext statt Chat-Gedaechtnis.

Qdrant als dedizierten Knowledge-Index aufbauen.
Ingestion aus Gitea/MkDocs definieren.
Secret- und Binary-Filter hart einbauen.
Kundenkontexte strikt trennen.
OpenCode-Projekte mit Knowledge-Manifest ausstatten.
Open WebUI Knowledge aus bereinigten Markdown-Quellen synchronisieren.

Phase 4: Agent Runtime¶

Ziel: laengere Aufgaben ueberleben Sessions und Fehler.

PostgreSQL fuer Agent-Tasks/Runs/Approvals nutzen.
Task-Statusmodell definieren:
queued
running
needs_approval
failed_retryable
failed_final
completed
Retry-/Recovery-Regeln definieren.
n8n fuer Benachrichtigungen und Scheduling nutzen.
OpenHands isoliert testen fuer repo-lange Jobs, nicht als Ersatz fuer OpenCode.

Phase 5: Sichere Write-Automation¶

Ziel: produktive Infrastruktur-Aenderungen mit Kontrolle.

SSH MCP mit Allowlist und Session-Logging.
PowerShell MCP fuer M365/Intune/AD mit eingeschraenkten Rollen.
Proxmox MCP erst read-only, dann kontrollierte Writes.
NetBox Write-Flows fuer geplante IP/VLAN/Device-Aenderungen.
Change-PR in Gitea als Pflicht vor produktiven Writes.

Technische Schulden¶

Tool-Schema-Probleme in OpenCode sind nur teilweise durch Regeln abgefangen.
NetBox ist produktiv, aber Agent-Zugriff fehlt noch strukturiert.
n8n ist installiert, aber nicht vollstaendig produktiv eingebunden.
Open WebUI nutzt fuer rohe Modelle BYPASS_MODEL_ACCESS_CONTROL=True; langfristig besser echte Model-Records/ACLs pflegen.
SearXNG ist fuer Open WebUI angebunden, aber noch nicht sauber als OpenCode-MCP.
Kein zentraler Observability-Stack fuer Agent-/MCP-Runs.
Kein einheitlicher Run-/Approval-Datenspeicher.
IPv6/DNS im LAN war stoeranfaellig und muss dauerhaft in UniFi/Netzplanung bereinigt werden.

Nicht empfohlen¶

OpenCode durch ein anderes Frontend ersetzen.
LangChain als zentrale Plattform einfuehren.
Open WebUI zum Haupt-Agenten fuer SSH/Infra-Changes machen.
NetBox-Daten in Markdown duplizieren statt referenzieren/exportieren.
Secrets direkt in OpenCode-Projektdateien oder Prompts speichern.
Autonome produktive SSH-/Firewall-/Proxmox-Aenderungen ohne Approval.

Naechste konkrete Schritte¶

n8n finalisieren und nur intern/NPM-geschuetzt bereitstellen.
NetBox read-only Service-Token erstellen und in Vaultwarden ablegen.
Einen lanstyle-agent-runtime Gitea-Ordner/Repo anlegen fuer:
MCP-Konfiguration
Tool-Risikoklassen
Modellrouting
Approval-Regeln
Runbook-Templates
FastMCP-Prototyp fuer netbox-readonly oder proxmox-readonly bauen.
Qdrant als dedizierten Knowledge-Index planen, aber erst nach sauberem Ingestion-Design installieren.
OpenCode-Regeln gegen Tool-Mismatch weiter haerten.
Observability minimal starten: strukturierte Logs, Run-ID, Task-ID, Git-Commit.