Kontrol

Tu máquina. Tus agentes. Tu compuerta de aprobación.

Kontrol es un plano de control autohospedado para extender agentes de codificación WebUI y CLI de una manera específica y controlada por revisión. Expone tus archivos de proyecto locales a través de MCP, despacha trabajo acotado a agentes ACP registrados, devuelve los resultados a través de la revisión humana y aplica políticas sobre las herramientas y rutas que los agentes pueden tocar.

Tú lo ejecutas en tu máquina, lo expones a través de un túnel que controlas y decides qué agentes pueden operar, qué pueden hacer y cuándo su trabajo puede aterrizar.

Qué lo hace diferente

La mayoría de los puentes de servidor de archivos MCP se detienen en «leer/escribir/editar». Kontrol añade tres capas encima:

Ralphie Muntz Loop — Los agentes envían trabajo para revisión humana. La superficie de revisión (WebUI o cualquier cliente MCP) muestra el diff. El humano aprueba, solicita cambios o rechaza. El agente continúa desde un estado de retroalimentación persistente — incluso si el proceso del agente murió y se reinició.

Bandeja de salida de continuación — Cada decisión de revisión genera un paquete de continuación estructurado con veredicto, acciones requeridas e instrucciones de reanudación. El paquete cruza desde la superficie de revisión hasta el siguiente turno del agente, por lo que el trabajo continúa sin perder contexto.

Modo de políticas — Reglas de aprobación por herramienta y por ruta. Un comando peligroso puede requerir una aprobación única, o puedes aprobarlo para una sesión completa del espacio de trabajo. La inspección de solo lectura sigue siendo rápida; las operaciones destructivas se pausan para el juicio humano.

Debajo de todo hay estado de flujo de trabajo transaccional con un registro de eventos de solo adición: los envíos, comentarios, aprobaciones, continuaciones, ejecuciones y decisiones de políticas se persisten en SQLite, y el flujo de eventos despierta a los observadores de WebUI y a los agentes bloqueados.

Related MCP server: safe-code-mcp

Instalación

Kontrol requiere Node >=22.19 <27.

El nombre del paquete npm está reservado para @b-a-m-n/kontrol, pero el paquete público aún no se ha publicado. Instala desde GitHub por ahora:

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

Si no usas claves SSH con GitHub, usa la URL HTTPS:

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

Para desarrollo desde el código fuente, clona el repositorio y enlaza la CLI localmente:

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

Para iniciar la pila completa de desarrollo local (servidor MCP, adaptadores ACP configurados y túnel MCP seguro) desde este checkout, usa:

kontrol up

kontrol up usa el .env del checkout y realiza las mismas comprobaciones previas y de disponibilidad que start-all.sh.

El checkout también proporciona ./restart-kontrol.sh, que ejecuta el mismo lanzador transaccional. Construye y verifica la generación de reemplazo antes de detener los procesos antiguos gestionados y revierte si falla una etapa de disponibilidad.

Solo para entornos de CI o sandbox restringidos, establece KONTROL_SKIP_PREFLIGHT_TESTS=true para omitir el conjunto completo de pruebas; el resto de comprobaciones previas y de disponibilidad siguen habilitadas.

Durante la configuración, Kontrol solicita:

• las carpetas de proyectos locales que los agentes pueden abrir

• el puerto local, normalmente 7676

• tu URL base HTTPS pública de Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel u otro proxy inverso

Usa el origen público sin /mcp:

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

Cuando el cliente se conecta, Kontrol abre una página de aprobación con la contraseña de propietario. Introduce la contraseña que imprime kontrol init. También se guarda en:

~/.kontrol/auth.json

Mantén esa contraseña en privado.

Conecta cualquier cliente MCP

El endpoint local predeterminado:

http://127.0.0.1:7676/mcp

GET /healthz informa de la vivacidad del proceso y de la identidad de compilación integrada. GET /core-readyz comprueba la base de datos propia de KONTROL, el manejador MCP, la inicialización de espacio de trabajo/revisión/ACP y la identidad de compilación en tiempo de ejecución mientras los adaptadores aún se están iniciando. GET /readyz es la disponibilidad operativa estricta: también requiere agentes trabajadores configurados y activos. El lanzador además realiza una inicialización MCP real, descubrimiento de agentes, apertura de espacio de trabajo, lectura de archivos y una prueba de ida y vuelta con bash antes de declarar la pila lista.

La mayoría de los usuarios se conectan a través de un túnel HTTPS público:

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

Kontrol habla MCP estándar sobre HTTP Streamable. Cualquier cliente compatible funciona: ChatGPT, Claude, Codex, Cursor, Windsurf, herramientas personalizadas.

OpenAI Secure MCP Tunnel

Para conectar Kontrol a ChatGPT sin exponer un puerto de entrada, ejecútalo localmente y enruta ChatGPT a través de un OpenAI Secure MCP Tunnel. En esa configuración usa KONTROL_AUTH_MODE=tunnel: Kontrol enlaza una dirección de loopback y desactiva su propia puerta de autenticación en /mcp, por lo que ChatGPT se conecta con No Authentication. El control de acceso se delega en el túnel y en el espacio de trabajo de OpenAI que lo posee. OAuth (el valor predeterminado para despliegues públicos) está intencionadamente desactivado aquí, porque su servidor de autorización no es accesible a través del túnel.

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

Registra el servidor en el cliente del túnel con No Authentication, apuntando al origen de loopback. El lanzador gestionado del checkout (./start-all.sh) mantiene un supervisor persistente en ejecución después del arranque y repara los componentes de túnel/adaptador fallidos mediante reinicios con umbral:

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

El lanzador usa KONTROL_TUNNEL_PROFILE (por defecto sample_mcp_with_dcr). Si ese perfil apunta a un túnel retirado o desactualizado, establece KONTROL_TUNNEL_ID=tunnel_... en .env después de crear o seleccionar el registro actual en OpenAI Tunnels, luego reinicia la pila y vuelve a conectar el conector de ChatGPT a ese mismo ID de túnel.

El WebUI de revisión se sirve como un recurso de MCP App autocontenido (su CSS y JS están incrustados en un único workspace-app.html), por lo que el iframe de ChatGPT no necesita hacer fetch a localhost. Consulta la Referencia de configuración para conocer todas las reglas de seguridad.

Cada mcp-session-id de MCP es un contexto de transporte aislado. Kontrol no agrupa sesiones solo porque los clientes compartan un nombre lógico, por lo que varias conversaciones pueden usar el servidor de forma concurrente. La continuidad del espacio de trabajo y de la revisión se lleva mediante IDs persistentes explícitos, en lugar de asumir que transportes separados pertenecen a una misma conversación.

Qué pueden hacer los agentes

Una vez conectado, un agente puede abrir una carpeta de proyecto aprobada como espacio de trabajo y:

• leer, escribir y editar archivos

• buscar código e inspeccionar directorios

• ejecutar comandos de shell para pruebas, compilaciones, git y scripts de paquetes

• usar worktrees de Git aislados para sesiones paralelas

• seguir las instrucciones del proyecto de AGENTS.md y CLAUDE.md

• descubrir habilidades locales del agente desde tus carpetas de habilidades

• mostrar tarjetas de herramientas y resúmenes de cambios opcionales en hosts compatibles con ChatGPT Apps

• enviar trabajo para revisión humana y continuar desde los comentarios

Ralphie Muntz Loop

El bucle de revisión está basado en eventos y es independiente del proveedor:

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

Este bucle vive en el registro de eventos de Kontrol, no en ningún host específico. Puedes revisar los envíos desde la misma interfaz que usas para chatear, desde un terminal o desde una herramienta futura.

Nombres de habilidades

El proyecto incluye algunas habilidades de agente deliberadamente memorables. Los nombres no son la superficie del producto; son identificadores de protocolo para el bucle:

• ralphie-muntz-loop es el contrato del lado del trabajador. El agente CLI realiza trabajo acotado, envía un diff, espera comentarios y se reanuda únicamente desde el estado de revisión persistente.

• nelson-wiggum-loop es el contrato del lado del revisor. El revisor WebUI o MCP inicia el trabajo, inspecciona el envío y es el único lado autorizado para decir que el trabajo está terminado.

• kontrol-supervised-mission es el contrato de control de misión. Añade objetivo, criterios, hallazgos, evidencia, órdenes de trabajo y bloqueadores de aprobación sobre el bucle de transporte.

Los nombres humorísticos hacen que el encuentro sea fácil de recordar. El modelo de autoridad es serio: los trabajadores no se aprueban a sí mismos, la revisión está vinculada al envío exacto y a la instantánea del espacio de trabajo, y la finalización está condicionada por el revisor o el predicado de la misión.

Modo de políticas

Controla qué operaciones requieren aprobación humana:

# 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

Modos:

Cuando una llamada requiere aprobación, la invocación de la herramienta del agente se bloquea (long-poll) hasta que un humano decide. «Aprobar para la sesión de trabajo» almacena en caché la decisión durante el resto de la sesión de trabajo para que las operaciones repetidas no vuelvan a preguntar; «Aprobar para el espacio de trabajo» la almacena hasta que el espacio de trabajo se cierra; «Aprobar una vez» no la almacena.

Modelo mental

Kontrol es un buzón de revisión persistente y una autoridad de políticas, no solo un servidor de archivos.

Tú decides qué raíces están permitidas. Tú decides qué herramientas requieren aprobación. El agente hace su trabajo, lo envía para revisión y continúa desde comentarios estructurados. El estado de flujo de trabajo persistente y el registro de eventos de solo adición son la autoridad de la que leen todas las superficies: CLI, WebUI, herramientas MCP y adaptadores ACP.

Para una sesión normal:

1. Inicia tu túnel.

2. Ejecuta kontrol serve.

3. Conecta tu agente MCP a la URL pública /mcp.

4. Aprueba la conexión con la contraseña de propietario.

5. Pide al agente que abra un proyecto dentro de una de tus raíces permitidas.

6. Revisa los envíos a medida que llegan.

Documentación

• Guía de configuración

• Flujo de trabajo de codificación

• Referencia de configuración

• Modelo de seguridad

• Solución de problemas

Soporte de plataformas

kontrol doctor

Atribución

Kontrol surgió de una idea que había estado dando vueltas durante un tiempo, y que dejé a un lado porque la capa local de MCP/espacio de trabajo era la parte difícil de hacer bien. Cuando vi que Waishnav había construido DevSpace, usé esa implementación MCP como base y la extendí en la dirección que había estado tratando de alcanzar.

El proyecto original DevSpace se distribuye bajo la Licencia MIT. Kontrol conserva esa atribución mientras añade despacho de trabajadores ACP, bucles de revisión persistentes, misiones supervisadas, aprobaciones de políticas e integraciones de adaptadores. Puedo ver cómo este estilo de plano de control de agentes local y con revisión podría ser útil más allá de mi propia configuración, por lo que el fork ahora tiene su propio nombre y dirección de producto.

Desarrollo local

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