Kontrol

당신의 머신. 당신의 에이전트. 당신의 승인 게이트.

Kontrol은 WebUI 및 CLI 코딩 에이전트를 특정한 검토 게이트 방식으로 확장하기 위한 자체 호스팅 컨트롤 플레인입니다. 로컬 프로젝트 파일을 MCP로 노출하고, 등록된 ACP 에이전트에 한정된 작업을 디스패치하며, 결과를 인간 검토로 다시 라우팅하고, 에이전트가 접근할 수 있는 도구와 경로에 대한 정책을 적용합니다.

당신은 자신의 머신에서 실행하고, 당신이 통제하는 터널로 노출하며, 어떤 에이전트가 작동할 수 있는지, 무엇을 할 수 있는지, 언제 작업이 반영되도록 허용할지를 결정합니다.

차별화되는 점

대부분의 MCP 파일 서버 브리지는 "읽기/쓰기/편집"에서 멈춥니다. Kontrol은 그 위에 세 가지 계층을 추가합니다:

Ralphie Muntz Loop — 에이전트가 인간 검토를 위해 작업을 제출합니다. 검토 인터페이스(WebUI 또는 모든 MCP 클라이언트)에 diff가 표시됩니다. 인간이 승인하거나, 변경을 요청하거나, 거부합니다. 에이전트는 지속적인 피드백 상태에서 계속 진행합니다 — 에이전트 프로세스가 죽었다가 재시작되어도 마찬가지입니다.

Continuation Outbox — 모든 검토 결정은 평결, 필수 조치, 재개 지침이 포함된 구조화된 연속(continuation) 패킷을 생성합니다. 패킷은 검토 인터페이스에서 다음 에이전트 턴으로 전달되므로 맥락을 잃지 않고 작업이 계속됩니다.

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

GitHub에서 SSH 키를 사용하지 않는다면 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 어댑터, 보안 MCP 터널)을 시작하려면 다음을 사용하세요:

kontrol up

kontrol up은 체크아웃의 .env를 사용하며 start-all.sh와 동일한 사전 점검 및 준비 상태(readiness) 검사를 수행합니다.

체크아웃에는 동일한 트랜잭션 런처를 실행하는 ./restart-kontrol.sh도 포함되어 있습니다. 이 스크립트는 기존 소유 프로세스를 중지하기 전에 대체 생성본을 빌드하고 검증하며, 준비 상태 단계가 실패하면 롤백합니다.

제한된 CI 또는 샌드박스 환경에서만 전체 테스트 스위트를 건너뛰도록 KONTROL_SKIP_PREFLIGHT_TESTS=true를 설정하세요. 다른 모든 사전 점검 및 준비 상태 검사는 계속 활성화됩니다.

설치 중에 Kontrol은 다음을 요청합니다:

• 에이전트가 열 수 있는 로컬 프로젝트 폴더

• 로컬 포트, 보통 7676

• Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel 또는 다른 리버스 프록시의 공개 HTTPS 기본 URL

/mcp 없이 공개 origin을 사용하세요:

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

클라이언트가 연결되면 Kontrol은 Owner 비밀번호 승인 페이지를 엽니다. kontrol init이 출력한 비밀번호를 입력하세요. 이 비밀번호는 다음 위치에도 저장됩니다:

~/.kontrol/auth.json

그 비밀번호를 안전하게 보관하세요.

모든 MCP 클라이언트 연결

기본 로컬 엔드포인트:

http://127.0.0.1:7676/mcp

GET /healthz는 프로세스 활성 상태와 포함된 빌드 식별자를 보고합니다. GET /core-readyz는 어댑터가 아직 시작되는 동안 KONTROL 자체 데이터베이스, MCP 핸들러, 워크스페이스/검토/ACP 초기화, 런타임 빌드 식별자를 확인합니다. GET /readyz는 엄격한 운영 준비 상태입니다. 활성 상태로 구성된 워커 에이전트도 필요로 합니다. 런처는 또한 스택이 준비되었다고 선언하기 전에 실제 MCP initialize, 에이전트 검색, 워크스페이스 열기, 파일 읽기, bash 왕복을 수행합니다.

대부분의 사용자는 공개 HTTPS 터널을 통해 연결합니다:

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

Kontrol은 Streamable HTTP를 통해 표준 MCP를 사용합니다. 호환되는 모든 클라이언트가 작동합니다: ChatGPT, Claude, Codex, Cursor, Windsurf, 커스텀 도구.

OpenAI 보안 MCP 터널

Kontrol을 인바운드 포트를 노출하지 않고 ChatGPT에 연결하려면 로컬에서 실행하고 OpenAI Secure MCP Tunnel을 통해 ChatGPT를 라우팅하세요. 이 구성에서는 KONTROL_AUTH_MODE=tunnel을 사용합니다. Kontrol은 루프백 주소에 바인딩하고 /mcp에서 자체 인증 게이트를 비활성화하므로 ChatGPT는 No Authentication으로 연결합니다. 접근 제어는 터널과 이를 소유한 OpenAI 워크스페이스에 위임됩니다. OAuth(공개 배포의 기본값)는 의도적으로 꺼져 있습니다. 인증 서버가 터널을 통해 도달할 수 없기 때문입니다.

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

터널 클라이언트에서 서버를 루프백 origin을 가리키도록 No Authentication으로 등록하세요. 관리형 체크아웃 런처(./start-all.sh)는 시작 후 지속적인 슈퍼바이저를 계속 실행하며 임계값 기반 재시작을 사용하여 실패한 터널/어댑터 구성 요소를 복구합니다:

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

런처는 KONTROL_TUNNEL_PROFILE(기본값 sample_mcp_with_dcr)을 사용합니다. 해당 프로필이 폐기되었거나 오래된 터널을 가리키는 경우, OpenAI Tunnels에서 현재 등록을 생성하거나 선택한 후 .env에 KONTROL_TUNNEL_ID=tunnel_...를 설정하고 스택을 재시작한 다음 ChatGPT 커넥터를 동일한 터널 ID에 다시 연결하세요.

검토 WebUI는 자체 포함된 MCP App 리소스로 제공됩니다(CSS와 JS가 단일 workspace-app.html에 인라인됨). 따라서 ChatGPT iframe은 localhost 가져오기가 필요하지 않습니다. 전체 보안 규칙은 Configuration Reference를 참조하세요.

각 MCP mcp-session-id는 격리된 전송 컨텍스트입니다. Kontrol은 클라이언트가 논리적 이름을 공유한다는 이유만으로 세션을 풀링하지 않으므로 여러 대화가 동시에 서버를 사용할 수 있습니다. 워크스페이스 및 검토 연속성은 별도의 전송이 하나의 대화에 속한다고 가정하는 대신 명시적인 지속 ID로 전달됩니다.

에이전트가 할 수 있는 작업

연결되면 에이전트는 승인된 프로젝트 폴더를 워크스페이스로 열고 다음을 수행할 수 있습니다:

• 파일 읽기, 쓰기, 편집

• 코드 검색 및 디렉터리 검사

• 테스트, 빌드, 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은 미션 컨트롤 계약입니다. 전송 루프 위에 목표, 기준, 발견 사항, 증거, 작업 지시, 승인 차단기를 추가합니다.

농담 같은 이름은 만남을 기억하기 쉽게 만듭니다. 권한 모델은 엄격합니다. 워커는 스스로를 승인하지 않으며, 검토는 정확한 제출물과 워크스페이스 스냅샷에 바인딩되고, 완료는 검토자 또는 미션 조건에 의해 게이트됩니다.

정책 모드

인간 승인이 필요한 작업을 제어하세요:

# 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

모드:

호출에 승인이 필요하면 에이전트의 도구 호출은 인간이 결정할 때까지 차단됩니다(롱폴링). "Approve for work session"은 남은 작업 세션 동안 결정을 캐시하여 반복 작업이 다시 프롬프트되지 않게 합니다. "Approve for workspace"는 워크스페이스가 닫힐 때까지 캐시하고, "Approve once"는 캐시하지 않습니다.

멘탈 모델

Kontrol은 단순한 파일 서버가 아니라 지속적인 검토 사서함이자 정책 권한 기관입니다.

허용할 루트를 결정합니다. 승인이 필요한 도구를 결정합니다. 에이전트는 작업을 수행하고, 검토를 위해 제출하며, 구조화된 피드백에서 계속 진행합니다. 지속적인 워크플로 상태와 추가 전용 이벤트 로그는 CLI, WebUI, MCP 도구, ACP 어댑터 등 모든 표면이 읽는 권한 소스입니다.

일반적인 세션의 경우:

1. 터널을 시작합니다.

2. kontrol serve를 실행합니다.

3. MCP 에이전트를 공개 /mcp URL에 연결합니다.

4. Owner 비밀번호로 연결을 승인합니다.

5. 에이전트에게 허용된 루트 중 하나에서 프로젝트를 열도록 요청합니다.

6. 제출물이 도착하면 검토합니다.

문서

• 설정 가이드

• 코딩 워크플로

• 구성 참조

• 보안 모델

• 문제 해결

플랫폼 지원

kontrol doctor

저작자 표기

Kontrol은 제가 한동안 고민하던 아이디어에서 시작되었습니다. 로컬 MCP/워크스페이스 계층이 제대로 만들기 어려운 부분이었기 때문에 한동안 보류해 두었죠. 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