KeyAI PC Commander

Windows UI and MCP gateway for a local KeyAI Agent Host. This repository contains the Commander source and its stdio MCP adapter. It does not include Agent Host, DesktopCommanderMCP, the OpenAI tunnel client, credentials, local profiles, or runtime data.

The UI and MCP server listen on 127.0.0.1 only. The stdio adapter forwards requests to the local MCP server; a separately configured Secure MCP Tunnel can make that adapter available to ChatGPT. The Host API key remains on the computer and is read by Commander from the Host runtime directory.

Requirements

• Windows and Node.js 22.16 or later.

• A running KeyAI Agent Host with its config.json and runtime/token in hostRoot.

• A locally installed MCP process adapter exposing DesktopCommanderMCP compatible terminal tools (start_process, interact_with_process, read_process_output, force_terminate). Set its entry file in dcEntry.

• An OpenAI Secure MCP Tunnel client only if you want cloud ChatGPT access. Set its executable path in tunnelClient. It is not bundled here.

Related MCP server: Agent Gateway MCP

Run locally

npm ci
Copy-Item config.example.json config.json

Edit config.json: set hostRoot, dcEntry, tunnelClient, and the absolute roots[].path directories for this PC. Start the Host; Commander starts the local terminal adapter when needed. Then run:

npm start

In another PowerShell window, run powershell -NoProfile -File .\windows\launch.ps1 to open the authenticated local UI. The first server start generates random keys in the ignored runtime/ directory. Keep that directory private. UI and MCP default to ports 17862 and 17863. Change the ports in config.json if needed.

For a local MCP client, use node <this-repository>\src\stdio.mjs for read-only tools, or add --approval to expose request_action and review_action. A cloud ChatGPT connection needs a separate tunnel runtime that launches the stdio adapter; a 127.0.0.1 URL is not a cloud endpoint. Never put the Host API key, Commander runtime keys, or a tunnel credential into the ChatGPT app manifest.

Action policy

approvalPolicy.mode supports manual, balanced, and automatic:

Choose automatic only for a trusted tunnel and account. It removes Commander approval prompts; it does not change ChatGPT's own permissions. File path restrictions and revision checks still apply to file tools, but a shell command is not sandboxed. Restart Commander after changing config.json.

The MCP review_action tool accepts only an existing action ID. In manual and balanced modes it can request a one-time decision through MCP elicitation when the client supports it; the local UI is another review path. action_status reports completion or pending state. Reuse the same request_id when polling or retrying an uncertain response.

The action journal keeps recent requests for one approval TTL after completion (10 minutes in the example). It also limits concurrent pending requests and aggregate stored record size. After a record is retired, an old ID is no longer a deduplication key; use a new ID only when you intend a new action.

Security and scope

The read-only and action-enabled MCP HTTP routes use separate local bearer keys. The UI uses a short-lived launch code, an HttpOnly session cookie, and a CSRF token. The listeners reject foreign Host and Origin headers. Secrets, profiles, backup data, model files, and installation logs are intentionally excluded from this repository. The gateway is not an OS sandbox; anyone who can act through an authorized write-enabled MCP connection can request actions allowed by the configured policy.

The Host and terminal adapter are external dependencies. The included tests use stubs for them; they do not establish end-to-end compatibility with every Host or ChatGPT release.

Tests

npm test

The tests create temporary directories and mock Host/terminal calls. An actual ChatGPT end-to-end check requires your own Host and tunnel setup.

Licensed under MIT; see LICENSE.