Kontrol

Ваша машина. Ваши агенты. Ваш этап утверждения.

Kontrol — это самостоятельно размещаемая плоскость управления для расширения WebUI- и CLI-агентов разработки кода определённым образом, с обязательной проверкой. Она открывает доступ к вашим локальным файлам проекта через MCP, отправляет ограниченные задачи зарегистрированным ACP-агентам, направляет результаты на проверку человеком и обеспечивает соблюдение политик в отношении инструментов и путей, к которым агенты могут обращаться.

Вы запускаете её на своей машине, публикуете через тоннель, которым управляете, и решаете, каким агентам разрешено работать, что они могут делать и когда их работа может быть принята.

В чём отличие

Большинство MCP-мостов файлового сервера останавливаются на «чтение/запись/редактирование». Kontrol добавляет поверх три уровня:

Ralphie Muntz Loop — агенты отправляют работу на проверку человеку. Поверхность проверки (WebUI или любой MCP-клиент) показывает diff. Человек одобряет, запрашивает изменения или отклоняет. Агент продолжает из устойчивого состояния обратной связи — даже если процесс агента завершился и перезапустился.

Continuation Outbox — каждое решение проверки формирует структурированный пакет продолжения с вердиктом, требуемыми действиями и инструкциями по возобновлению. Пакет передаётся от поверхности проверки к следующему ходу агента, поэтому работа продолжается без потери контекста.

Policy Mode — правила утверждения для каждого инструмента и каждого пути. Опасная команда может потребовать разового одобрения, или вы можете одобрить её на всю сессию рабочей области. Проверка только для чтения остаётся быстрой; разрушительные операции останавливаются для решения человека.

В основе всего лежит транзакционное состояние рабочего процесса с журналом событий только на добавление: отправки, обратная связь, одобрения, продолжения, запуски и решения по политикам сохраняются в SQLite, а поток событий пробуждает наблюдателей WebUI и заблокированных агентов.

Related MCP server: safe-code-mcp

Установка

Kontrol требует Node >=22.19 <27.

Имя npm-пакета зарезервировано для @b-a-m-n/kontrol, но публичный пакет ещё не опубликован. Пока установите из GitHub:

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

Если вы не используете SSH-ключи с GitHub, используйте HTTPS-URL:

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

Для разработки из исходников склонируйте репозиторий и свяжите CLI локально:

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

Чтобы запустить полный локальный стек разработки (MCP-сервер, настроенные ACP-адаптеры и Secure MCP tunnel) из этого чекаута, используйте:

kontrol up

kontrol up использует .env этого чекаута и выполняет те же предварительные проверки и проверки готовности, что и start-all.sh.

В чекауте также есть ./restart-kontrol.sh, который запускает тот же транзакционный лаунчер. Он собирает и проверяет заменяющее поколение перед остановкой старых принадлежащих процессов и откатывается, если этап проверки готовности не пройден.

Только для ограниченных CI- или песочных сред установите KONTROL_SKIP_PREFLIGHT_TESTS=true, чтобы пропустить полный набор тестов; все остальные предварительные проверки и проверки готовности остаются включёнными.

Во время настройки Kontrol запрашивает:

• локальные папки проекта, которые агентам разрешено открывать

• локальный порт, обычно 7676

• ваш публичный базовый HTTPS-URL от Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel или другого обратного прокси

Используйте публичный origin без /mcp:

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

Когда клиент подключается, Kontrol открывает страницу одобрения с паролем владельца. Введите пароль, выведенный kontrol init. Он также хранится в:

~/.kontrol/auth.json

Держите этот пароль в тайне.

Подключение любого MCP-клиента

Локальная конечная точка по умолчанию:

http://127.0.0.1:7676/mcp

GET /healthz сообщает о живости процесса и встроенной идентичности сборки. GET /core-readyz проверяет собственную базу данных KONTROL, MCP-обработчик, инициализацию workspace/review/ACP и идентичность сборки во время выполнения, пока адаптеры ещё запускаются. GET /readyz — это строгая операционная готовность: он также требует живых настроенных воркер-агентов. Лаунчер дополнительно выполняет фактические MCP initialize, обнаружение агентов, открытие рабочей области, чтение файла и bash round trip, прежде чем объявить стек готовым.

Большинство пользователей подключаются через публичный HTTPS-тоннель:

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

Kontrol говорит на стандартном MCP через Streamable HTTP. Подойдёт любой совместимый клиент: ChatGPT, Claude, Codex, Cursor, Windsurf, собственные инструменты.

OpenAI Secure MCP Tunnel

Чтобы подключить Kontrol к ChatGPT без открытия входящего порта, запустите его локально и направьте ChatGPT через OpenAI Secure MCP Tunnel. В такой конфигурации используйте KONTROL_AUTH_MODE=tunnel: Kontrol привязывается к loopback-адресу и отключает собственный шлюз аутентификации на /mcp, поэтому ChatGPT подключается с No Authentication. Контроль доступа делегируется тоннелю и рабочей области OpenAI, которой он принадлежит. OAuth (по умолчанию для публичных развёртываний) здесь намеренно отключён, потому что его сервер авторизации недоступен через тоннель.

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

Зарегистрируйте сервер в туннельном клиенте с No Authentication, указав loopback-origin. Управляемый лаунчер чекаута (./start-all.sh) после запуска держит постоянный супервизор и восстанавливает отказавшие компоненты туннеля/адаптеров с помощью перезапусков по пороговому принципу:

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

Лаунчер использует KONTROL_TUNNEL_PROFILE (по умолчанию sample_mcp_with_dcr). Если этот профиль указывает на выведенный из эксплуатации или устаревший туннель, задайте KONTROL_TUNNEL_ID=tunnel_... в .env после создания или выбора текущей регистрации в OpenAI Tunnels, затем перезапустите стек и подключите коннектор ChatGPT к этому же tunnel ID.

WebUI проверки подаётся как самодостаточный ресурс MCP App (его CSS и JS встроены в один workspace-app.html), поэтому iframe ChatGPT не требует обращений к localhost. Полные правила безопасности см. в Configuration Reference.

Каждый MCP mcp-session-id — это изолированный транспортный контекст. Kontrol не объединяет сессии только потому, что клиенты используют одно логическое имя, поэтому несколько разговоров могут работать с сервером одновременно. Непрерывность рабочей области и проверки обеспечивается явными устойчивыми ID, а не предположением, что отдельные транспорты принадлежат одному разговору.

Что могут делать агенты

После подключения агент может открыть одобренную папку проекта как рабочую область и:

• читать, записывать и редактировать файлы

• искать код и просматривать каталоги

• запускать shell-команды для тестов, сборок, git и скриптов пакетов

• использовать изолированные Git worktree для параллельных сессий

• следовать инструкциям проекта из AGENTS.md и CLAUDE.md

• обнаруживать локальные навыки агентов в ваших папках навыков

• показывать карточки инструментов и необязательные сводки изменений в хостах, совместимых с ChatGPT Apps

• отправлять работу на проверку человеку и продолжать с учётом обратной связи

Ralphie Muntz Loop

Цикл проверки управляется событиями и не зависит от провайдера:

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

Этот цикл живёт в журнале событий Kontrol, а не в каком-то конкретном хосте. Вы можете просматривать отправки из того же интерфейса, где общаетесь, из терминала или из будущего инструмента.

Имена навыков

Проект включает несколько специально запоминающихся навыков агентов (Agent Skills). Эти имена — не пользовательский интерфейс продукта, а протокольные дескрипторы цикла:

• ralphie-muntz-loop — контракт на стороне воркера. CLI-агент выполняет ограниченную работу, отправляет diff, ждёт обратной связи и возобновляет работу только из устойчивого состояния проверки.

• nelson-wiggum-loop — контракт на стороне проверяющего. WebUI- или MCP-рецензент начинает работу, изучает отправку и является единственной стороной, которая вправе сказать, что работа завершена.

• kontrol-supervised-mission — контракт управления миссией. Он добавляет цель, критерии, выводы, доказательства, рабочие поручения и блокировщики утверждения поверх транспортного цикла.

Шутливые имена делают встречу лёгкой для запоминания. Модель полномочий серьёзна: воркеры не утверждают собственную работу, проверка привязана к конкретной отправке и снимку рабочей области, а завершение контролируется проверяющим или предикатом миссии.

Policy Mode

Управляйте тем, какие операции требуют одобрения человека:

# 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

Режимы:

Когда вызов требует одобрения, вызов инструмента агентом блокируется (long-poll), пока человек не примет решение. «Approve for work session» кэширует решение до конца рабочей сессии, так что повторные операции не запрашивают снова; «Approve for workspace» кэширует до закрытия рабочей области; «Approve once» не кэшируется.

Ментальная модель

Kontrol — это устойчивый почтовый ящик проверок и орган управления политиками, а не просто файловый сервер.

Вы решаете, какие корневые каталоги разрешены. Вы решаете, какие инструменты требуют одобрения. Агент выполняет работу, отправляет на проверку и продолжает на основе структурированной обратной связи. Устойчивое состояние рабочего процесса и журнал событий только на добавление — это источник полномочий, из которого читают все поверхности: CLI, WebUI, MCP-инструменты и ACP-адаптеры.

Для обычной сессии:

1. Запустите свой туннель.

2. Запустите kontrol serve.

3. Подключите MCP-агента к публичному URL /mcp.

4. Одобрите подключение паролем владельца.

5. Попросите агента открыть проект внутри одного из разрешённых корневых каталогов.

6. Просматривайте отправки по мере их поступления.

Документация

• Руководство по установке

• Рабочий процесс написания кода

• Справочник по конфигурации

• Модель безопасности

• Поиск и устранение неполадок

Поддержка платформ

kontrol doctor

Атрибуция

Kontrol вырос из идеи, которую я давно обдумывал, а затем отложил в сторону, потому что локальный уровень MCP/workspace было труднее всего довести до ума. Когда я увидел, что Waishnav создал DevSpace, я использовал эту MCP-реализацию как основу и расширил её в том направлении, к которому стремился.

Оригинальный проект DevSpace распространяется под лицензией MIT. Kontrol сохраняет эту атрибуцию, добавляя диспетчеризацию воркеров ACP, устойчивые циклы проверки, контролируемые миссии, утверждения по политикам и интеграции адаптеров. Я вижу, что такой локальный уровень управления агентами с проверкой может быть полезен не только в моей собственной схеме, поэтому форк теперь имеет собственное имя и направление продукта.

Локальная разработка

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