# 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.

## Run locally

```powershell
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:

```powershell
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`:

| Mode | Remote actions |
| --- | --- |
| `manual` (example default) | Every `request_action` waits for a local decision. |
| `balanced` | Bounded workspace text edits and fixed Node version checks run immediately; other actions wait. |
| `automatic` | Every supported Commander action runs immediately, including shell commands and Host jobs, with the Windows user's rights. |

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

```powershell
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](LICENSE).