Kontrol

Deine Maschine. Deine Agenten. Dein Genehmigungs-Gate.

Kontrol ist eine selbst gehostete Kontrollebene zur Erweiterung von WebUI- und CLI-Coding-Agenten auf eine spezifische, review-gesteuerte Weise. Es stellt deine lokalen Projektdateien über MCP bereit, sendet begrenzte Arbeit an registrierte ACP-Agenten, leitet Ergebnisse zur menschlichen Überprüfung zurück und setzt Richtlinien für die Tools und Pfade durch, die Agenten berühren dürfen.

Du betreibst es auf deiner Maschine, stellst es über einen Tunnel bereit, den du kontrollierst, und entscheidest, welche Agenten arbeiten dürfen, was sie tun können und wann ihre Arbeit übernommen werden darf.

Was es anders macht

Die meisten MCP-Dateiserver-Brücken enden bei „Lesen/Schreiben/Bearbeiten“. Kontrol fügt drei Ebenen hinzu:

Ralphie-Muntz-Loop — Agenten reichen Arbeit zur menschlichen Überprüfung ein. Die Review-Oberfläche (WebUI oder ein beliebiger MCP-Client) zeigt den Diff. Der Mensch genehmigt, fordert Änderungen an oder lehnt ab. Der Agent arbeitet aus dauerhaftem Feedback-Zustand weiter — selbst wenn der Agentenprozess gestorben und neu gestartet wurde.

Continuation-Outbox — Jede Review-Entscheidung erzeugt ein strukturiertes Fortsetzungspaket mit Urteil, erforderlichen Aktionen und Wiederaufnahme-Anweisungen. Das Paket wechselt von der Review-Oberfläche zum nächsten Agenten-Turn, sodass die Arbeit ohne Kontextverlust fortgesetzt wird.

Policy-Modus — Genehmigungsregeln pro Tool und pro Pfad. Ein gefährlicher Befehl kann eine einmalige Genehmigung erfordern, oder du kannst ihn für eine gesamte Workspace-Sitzung genehmigen. Schreibgeschützte Inspektion bleibt schnell; destruktive Operationen pausieren für menschliches Urteil.

Darunter liegt transaktionaler Workflow-Zustand mit einem append-only Ereignisprotokoll: Einreichungen, Feedback, Genehmigungen, Fortsetzungen, Läufe und Policy-Entscheidungen werden in SQLite gespeichert, und der Ereignisstrom weckt WebUI-Watcher und blockierte Agenten.

Related MCP server: safe-code-mcp

Installation

Kontrol erfordert Node >=22.19 <27.

Der npm-Paketname ist für @b-a-m-n/kontrol reserviert, aber das öffentliche Paket ist noch nicht veröffentlicht. Installiere vorerst von GitHub:

npm install -g git+ssh://git@github.com/B-A-M-N/Kontrol.git
kontrol init
kontrol serve

Wenn du keine SSH-Schlüssel mit GitHub verwendest, nutze die HTTPS-URL:

npm install -g git+https://github.com/B-A-M-N/Kontrol.git

Für die Quellcode-Entwicklung klone das Repository und verlinke die CLI lokal:

git clone git@github.com:B-A-M-N/Kontrol.git
cd Kontrol
npm install --include=dev
npm run build
npm link
kontrol init
kontrol serve

Um den vollständigen lokalen Entwicklungsstack (MCP-Server, konfigurierte ACP-Adapter und Secure-MCP-Tunnel) aus diesem Checkout zu starten, verwende:

kontrol up

kontrol up verwendet das .env des Checkouts und führt dieselben Preflight- und Bereitschaftsprüfungen wie start-all.sh durch.

Das Checkout bietet außerdem ./restart-kontrol.sh, das denselben transaktionalen Launcher ausführt. Es baut und verifiziert die Ersatzgeneration, bevor es alte eigene Prozesse stoppt, und führt einen Rollback durch, wenn eine Bereitschaftsstufe fehlschlägt.

Nur für eingeschränkte CI- oder Sandbox-Umgebungen setze KONTROL_SKIP_PREFLIGHT_TESTS=true, um die vollständige Testsuite zu überspringen; alle anderen Preflight- und Bereitschaftsprüfungen bleiben aktiviert.

Während der Einrichtung fragt Kontrol nach:

• den lokalen Projektordnern, die Agenten öffnen dürfen

• dem lokalen Port, normalerweise 7676

• deiner öffentlichen HTTPS-Basis-URL von Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel oder einem anderen Reverse-Proxy

Verwende den öffentlichen Ursprung ohne /mcp:

https://your-tunnel-host.example.com

Wenn der Client sich verbindet, öffnet Kontrol eine Owner-Passwort-Genehmigungsseite. Gib das Passwort ein, das kontrol init ausgibt. Es wird auch gespeichert in:

~/.kontrol/auth.json

Halte dieses Passwort geheim.

Beliebigen MCP-Client verbinden

Der Standard-Endpunkt lokal:

http://127.0.0.1:7676/mcp

GET /healthz meldet Prozess-Liveness und die eingebettete Build-Identität. GET /core-readyz prüft KONTROLs eigene Datenbank, den MCP-Handler, Workspace/Review/ACP-Initialisierung und die Laufzeit-Build-Identität, während die Adapter noch starten. GET /readyz ist strikte operative Bereitschaft: Es erfordert zusätzlich live konfigurierte Worker-Agenten. Der Launcher führt außerdem eine tatsächliche MCP-Initialisierung, Agenten-Erkennung, Workspace-Öffnung, Datei-Lesen und Bash-Roundtrip durch, bevor er den Stack als bereit erklärt.

Die meisten Benutzer verbinden sich über einen öffentlichen HTTPS-Tunnel:

https://your-tunnel-host.example.com/mcp

Kontrol spricht standardmäßiges MCP über Streamable HTTP. Jeder kompatible Client funktioniert: ChatGPT, Claude, Codex, Cursor, Windsurf, benutzerdefinierte Tools.

OpenAI Secure MCP Tunnel

Um Kontrol mit ChatGPT zu verbinden, ohne einen eingehenden Port freizugeben, führe es lokal aus und leite ChatGPT durch einen OpenAI Secure MCP Tunnel. In diesem Setup verwende KONTROL_AUTH_MODE=tunnel: Kontrol bindet eine Loopback-Adresse und deaktiviert sein eigenes Auth-Gate auf /mcp, sodass ChatGPT sich mit No Authentication verbindet. Die Zugriffskontrolle wird an den Tunnel und den OpenAI-Workspace delegiert, der ihn besitzt. OAuth (der Standard für öffentliche Bereitstellungen) ist hier absichtlich deaktiviert, da sein Autorisierungsserver über den Tunnel nicht erreichbar ist.

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

Registriere den Server im Tunnel-Client mit No Authentication, der auf den Loopback-Ursprung zeigt. Der verwaltete Checkout-Launcher (./start-all.sh) hält nach dem Start einen persistenten Supervisor am Leben und repariert fehlgeschlagene Tunnel-/Adapter-Komponenten mit Schwellenwert-Neustarts:

tunnel-client run \
  --mcp.server-url "http://127.0.0.1:7676/mcp"

Der Launcher verwendet KONTROL_TUNNEL_PROFILE (Standard sample_mcp_with_dcr). Wenn dieses Profil auf einen stillgelegten oder veralteten Tunnel zeigt, setze KONTROL_TUNNEL_ID=tunnel_... in .env, nachdem du die aktuelle Registrierung in OpenAI Tunnels erstellt oder ausgewählt hast, starte dann den Stack neu und verbinde den ChatGPT-Connector erneut mit derselben Tunnel-ID.

Die Review-WebUI wird als eigenständige MCP-App-Ressource bereitgestellt (ihr CSS und JS sind in eine einzelne workspace-app.html eingebettet), sodass das ChatGPT-Iframe keine localhost Abrufe benötigt. Siehe Configuration Reference für die vollständigen Sicherheitsregeln.

Jede MCP-mcp-session-id ist ein isolierter Transportkontext. Kontrol poolt keine Sitzungen, nur weil Clients einen logischen Namen teilen, sodass mehrere Konversationen den Server gleichzeitig verwenden können. Workspace- und Review-Kontinuität wird durch explizite dauerhafte IDs getragen, nicht durch die Annahme, dass separate Transporte zu einer Konversation gehören.

Was Agenten tun können

Sobald verbunden, kann ein Agent einen genehmigten Projektordner als Workspace öffnen und:

• Dateien lesen, schreiben und bearbeiten

• Code durchsuchen und Verzeichnisse inspizieren

• Shell-Befehle für Tests, Builds, Git und Paketskripte ausführen

• isolierte Git-Worktrees für parallele Sitzungen verwenden

• Projektanweisungen aus AGENTS.md und CLAUDE.md befolgen

• lokale Agenten-Skills aus deinen Skill-Ordnern entdecken

• Tool-Karten und optionale Änderungszusammenfassungen in ChatGPT-Apps-kompatiblen Hosts anzeigen

• Arbeit zur menschlichen Überprüfung einreichen und aus Feedback fortfahren

Ralphie-Muntz-Loop

Der Review-Loop ist ereignisgesteuert und provider-agnostisch:

Agent submits work → Kontrol captures diff, emits ReviewRequested
     ↓
Human reviews diff in WebUI / any MCP client
     ↓
Human approves, requests changes, or rejects
     ↓
Kontrol persists feedback event + generates continuation packet
     ↓
If agent is live: it unblocks and continues
If agent stopped: it reads feedback when it resumes

Dieser Loop lebt in Kontrols Ereignisprotokoll, nicht in einem bestimmten Host. Du kannst Einreichungen von derselben Oberfläche aus überprüfen, die du zum Chatten verwendest, von einem Terminal oder von einem zukünftigen Tool.

Skill-Namen

Das Projekt enthält einige bewusst einprägsame Agent Skills. Die Namen sind nicht die Produktoberfläche; sie sind Protokoll-Handles für den Loop:

• ralphie-muntz-loop ist der Worker-seitige Vertrag. Der CLI-Agent führt begrenzte Arbeit aus, reicht einen Diff ein, wartet auf Feedback und setzt nur aus dauerhaftem Review-Zustand fort.

• nelson-wiggum-loop ist der Reviewer-seitige Vertrag. Der WebUI- oder MCP-Reviewer startet Arbeit, inspiziert die Einreichung und ist die einzige Seite, die sagen darf, dass die Arbeit abgeschlossen ist.

• kontrol-supervised-mission ist der Missionskontroll-Vertrag. Er fügt Ziel, Kriterien, Befunde, Beweise, Arbeitsaufträge und Genehmigungs-Blocker über den Transport-Loop hinzu.

Die scherzhaften Namen machen das Rendezvous leicht zu merken. Das Autoritätsmodell ist ernst: Worker genehmigen sich nicht selbst, Review ist an die exakte Einreichung und Workspace-Snapshot gebunden, und der Abschluss wird durch den Reviewer oder das Missions-Prädikat gesteuert.

Policy-Modus

Steuere, welche Operationen menschliche Genehmigung erfordern:

# Require approval for bash, allow file edits freely
KONTROL_POLICY_TOOL_BASH=ask KONTROL_POLICY_TOOL_WRITE=allow

# Deny access to sensitive paths (structured JSON — the per-rule env format
# `KONTROL_POLICY_PATH_<glob>` is no longer supported; it is not valid
# shell assignment syntax)
KONTROL_POLICY_PATH_RULES='[{"pattern":"/etc/ssh/**","mode":"deny"}]'

# Default: ask for anything not explicitly allowed
KONTROL_POLICY_MODE=ask

Modi:

Wenn ein Aufruf Genehmigung erfordert, blockiert der Tool-Aufruf des Agenten (Long-Poll), bis ein Mensch entscheidet. „Für Arbeitssitzung genehmigen“ speichert die Entscheidung für den Rest der Arbeitssitzung, sodass wiederholte Operationen nicht erneut nachfragen; „Für Workspace genehmigen“ speichert, bis der Workspace geschlossen wird; „Einmal genehmigen“ speichert nicht.

Mentales Modell

Kontrol ist eine dauerhafte Review-Mailbox und Policy-Autorität, nicht nur ein Dateiserver.

Du entscheidest, welche Wurzeln erlaubt sind. Du entscheidest, welche Tools Genehmigung erfordern. Der Agent erledigt seine Arbeit, reicht zur Überprüfung ein und fährt aus strukturiertem Feedback fort. Dauerhafter Workflow-Zustand und das append-only Ereignisprotokoll sind die Autorität, aus der jede Oberfläche liest: CLI, WebUI, MCP-Tools und ACP-Adapter.

Für eine normale Sitzung:

1. Starte deinen Tunnel.

2. Führe kontrol serve aus.

3. Verbinde deinen MCP-Agenten mit der öffentlichen /mcp-URL.

4. Genehmige die Verbindung mit dem Owner-Passwort.

5. Bitte den Agenten, ein Projekt innerhalb einer deiner erlaubten Wurzeln zu öffnen.

6. Überprüfe Einreichungen, sobald sie eingehen.

Dokumentation

• Setup Guide

• Coding Workflow

• Configuration Reference

• Security Model

• Troubleshooting

Plattformunterstützung

kontrol doctor

Namensnennung

Kontrol entstand aus einer Idee, die ich schon eine Weile mit mir herumtrug, dann aber beiseitelegte, weil die lokale MCP/Workspace-Ebene der schwierige Teil war, den man richtig hinbekommen musste. Als ich sah, dass Waishnav DevSpace gebaut hatte, nutzte ich diese MCP-Implementierung als Basis und erweiterte sie in die Richtung, die ich erreichen wollte.

Das ursprüngliche DevSpace-Projekt wird unter der MIT-Lizenz vertrieben. Kontrol behält diese Namensnennung bei und fügt ACP-Worker-Dispatch, dauerhafte Review-Loops, überwachte Missionen, Policy-Genehmigungen und Adapter-Integrationen hinzu. Ich kann sehen, wie dieser Stil einer lokalen, review-gesteuerten Agenten-Kontrollebene über mein eigenes Setup hinaus nützlich sein könnte, daher hat der Fork jetzt einen eigenen Namen und eine eigene Produktrichtung.

Lokale Entwicklung

npm install --include=dev
npm run dev
npm run typecheck
npm test
npm run build
npm run start