Kontrol

あなたのマシン。あなたのエージェント。あなたの承認ゲート。

Kontrol は、WebUI および CLI コーディングエージェントを、特定のレビューゲート付きの方法で拡張するためのセルフホスト型コントロールプレーンです。ローカルのプロジェクトファイルを MCP 経由で公開し、登録済みの ACP エージェントに境界付きの作業を派遣し、結果を人間のレビューに戻し、エージェントが触れることのできるツールとパスに関するポリシーを適用します。

あなたは自分のマシンで実行し、自分が管理するトンネルで公開し、どのエージェントに操作を許可するか、何ができるか、いつ作業の着地を許可するかを決定します。

他と何が違うのか

ほとんどの MCP ファイルサーバーブリッジは「読み取り/書き込み/編集」で止まります。Kontrol はその上に3つのレイヤーを追加します:

Ralphie Muntz ループ — エージェントは人間のレビューのために作業を提出します。レビュー画面(WebUI または任意の MCP クライアント)には差分が表示されます。人間が承認、変更要求、または拒否を行います。エージェントは永続的なフィードバック状態から続行します — エージェントプロセスが終了して再起動した場合でも同様です。

継続アウトボックス — すべてのレビュー決定は、判定、必要なアクション、再開手順を含む構造化された継続パケットを生成します。パケットはレビュー画面から次のエージェントターンへ渡るため、コンテキストを失うことなく作業を継続できます。

ポリシーモード — ツール単位およびパス単位の承認ルール。危険なコマンドには1回限りの承認が必要な場合もあれば、ワークスペースセッション全体で承認することもできます。読み取り専用の検査は高速なまま維持され、破壊的な操作は人間の判断のために一時停止します。

その下には追記専用イベントログを備えたトランザクション型ワークフロー状態があります: 提出、フィードバック、承認、継続、実行、ポリシー決定は 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 アダプター、Secure MCP トンネル)を起動するには、次を使用します:

kontrol up

kontrol up はチェックアウトの .env を使用し、start-all.sh と同じ事前チェックと準備完了チェックを実行します。

チェックアウトには ./restart-kontrol.sh も用意されており、同じトランザクション型ランチャーを実行します。古い所有プロセスを停止する前に置換世代をビルドして検証し、準備完了ステージが失敗した場合はロールバックします。

制約のある CI またはサンドボックス環境のみで、KONTROL_SKIP_PREFLIGHT_TESTS=true を設定して完全なテストスイートをスキップできます。他のすべての事前チェックと準備完了チェックは有効のままです。

セットアップ中に、Kontrol は以下を尋ねます:

• エージェントが開くことを許可されるローカルプロジェクトフォルダー

• ローカルポート(通常は 7676)

• Cloudflare Tunnel、ngrok、Pinggy、Tailscale Funnel、または別のリバースプロキシからの公開 HTTPS ベース URL

/mcp なしの公開オリジンを使用してください:

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

クライアントが接続すると、Kontrol は Owner パスワード承認ページを開きます。kontrol init によって出力されたパスワードを入力してください。これは次の場所にも保存されています:

~/.kontrol/auth.json

そのパスワードは秘密に保ってください。

任意の MCP クライアントを接続する

デフォルトのローカルエンドポイント:

http://127.0.0.1:7676/mcp

GET /healthz はプロセスの生存性と組み込みビルド ID を報告します。GET /core-readyz は、アダプターがまだ起動中である間に、KONTROL 自身のデータベース、MCP ハンドラー、ワークスペース/レビュー/ACP の初期化、およびランタイムビルド ID をチェックします。GET /readyz は厳格な運用準備完了です: ライブで設定されたワーカーエージェントも必要とします。ランチャーはさらに、スタックが準備完了と宣言する前に、実際の MCP 初期化、エージェント検出、ワークスペースオープン、ファイル読み取り、bash ラウンドトリップを実行します。

ほとんどのユーザーは公開 HTTPS トンネル経由で接続します:

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

Kontrol は Streamable HTTP 上の標準 MCP を話します。互換性のあるクライアントならどれでも動作します: ChatGPT、Claude、Codex、Cursor、Windsurf、カスタムツール。

OpenAI Secure MCP トンネル

Kontrol をインバウンドポートを公開せずに ChatGPT に接続するには、ローカルで実行し、OpenAI Secure MCP Tunnel 経由で ChatGPT をルーティングします。そのセットアップでは KONTROL_AUTH_MODE=tunnel を使用します: Kontrol はループバックアドレスにバインドし、/mcp 上の自身の認証ゲートを無効化するため、ChatGPT は認証なしで接続します。アクセス制御はトンネルとそれを所有する OpenAI ワークスペースに委任されます。OAuth(公開デプロイメントのデフォルト)は、その認証サーバーがトンネル経由で到達できないため、ここでは意図的にオフになっています。

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

トンネルクライアントでサーバーを認証なしで登録し、ループバックオリジンを指すようにします。管理チェックアウトランチャー(./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 はクライアントが論理名を共有するという理由だけでセッションをプールしません。そのため、複数の会話がサーバーを同時に使用できます。ワークスペースとレビューの継続性は、別々のトランスポートが1つの会話に属すると想定するのではなく、明示的な永続 ID によって運ばれます。

エージェントができること

接続すると、エージェントは承認されたプロジェクトフォルダーをワークスペースとして開き、以下を行うことができます:

• ファイルの読み取り、書き込み、編集

• コードの検索とディレクトリの検査

• テスト、ビルド、git、パッケージスクリプト用のシェルコマンドの実行

• 並列セッション用の分離された Git ワークツリーの使用

• AGENTS.md と CLAUDE.md からのプロジェクト指示の遵守

• スキルフォルダーからのローカルエージェントスキルの発見

• ChatGPT Apps 互換ホストでのツールカードとオプションの変更サマリーの表示

• 人間のレビューのための作業の提出とフィードバックからの続行

Ralphie Muntz ループ

レビューループはイベント駆動型でプロバイダーに依存しません:

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 エージェントは境界付きの作業を行い、差分を提出し、フィードバックを待ち、永続的なレビュー状態からのみ再開します。

• 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

モード:

呼び出しに承認が必要な場合、エージェントのツール呼び出しは人間が決定するまでブロックされます(ロングポーリング)。「ワークセッション用に承認」は、繰り返しの操作が再プロンプトされないように、ワークセッションの残り期間その決定をキャッシュします。「ワークスペース用に承認」はワークスペースが閉じるまでキャッシュします。「1回だけ承認」はキャッシュしません。

メンタルモデル

Kontrol は永続的なレビューメールボックスとポリシー権限であり、単なるファイルサーバーではありません。

許可するルートを決定します。承認が必要なツールを決定します。エージェントは作業を行い、レビューのために提出し、構造化されたフィードバックから続行します。永続的なワークフロー状態と追記専用イベントログは、CLI、WebUI、MCP ツール、ACP アダプターなど、すべての画面が読み取る権限です。

通常のセッションの場合:

1. トンネルを開始します。

2. kontrol serve を実行します。

3. MCP エージェントを公開 /mcp URL に接続します。

4. Owner パスワードで接続を承認します。

5. エージェントに許可されたルートの1つの中のプロジェクトを開くように依頼します。

6. 提出物が届いたらレビューします。

ドキュメント

• Setup Guide

• Coding Workflow

• Configuration Reference

• Security Model

• Troubleshooting

プラットフォームサポート

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