Windows Remote MCP Control

English · 한국어

This project exposes an allowlisted Windows desktop-control MCP server over Streamable HTTP. It supports standards-compatible remote AI clients through OAuth 2.1 Authorization Code + PKCE, visual PNG responses, a local AI-control HUD, and multi-agent coordination. The earlier pairing-token exchange remains available for local clients.

Custom MCP guide · 한국어 커스텀 MCP 가이드 · Mobile installation guide with screenshots · 한국어 설치 가이드 · Reddit post drafts

Quick start

Download either Windows package from the public distribution Releases page. The source repository is private; the distribution repository publishes only runnable packages and SHA-256 verification data.

• Remote-MCP-Control-Setup-0.10.1-x64.exe: guided per-user installer with install-directory selection plus desktop and Start menu shortcuts.

• Remote-MCP-Control-Portable-0.10.1-x64.exe: no-install executable that can be launched directly.

The Windows packages use the same branded icon in the executable, taskbar, window, tray, installer, and shortcuts. They are not Authenticode-signed, so Windows SmartScreen can show an unknown-publisher warning. Download them only from the public distribution release, compare their SHA-256 values with SHA256SUMS.txt on the same release, and do not run them if a value differs. A trusted Windows code-signing certificate is required to remove this warning.

Get-FileHash -Algorithm SHA256 .\Remote-MCP-Control-*-0.10.1-x64.exe

MCP-Remote-Control-Launcher.cmd

With no command-line arguments this opens the Electron control center. On the first run it installs the locked Electron dependencies, then provides:

• a state-aware five-step first-connection wizard;

• a persistent 한국어 / English switch shared by the dashboard, tray menu, and desktop HUD;

• animated server/tunnel health and PID telemetry;

• separate Overview, Live desktop, Activity, AI connections, AI work sessions, Fixed domain, Permissions, and Media hub pages;

• a live primary-monitor preview;

• real-time per-AI tool, OAuth, mouse, keyboard, process, background-job, and workspace-file audit activity;

• owner-selected project roots, per-chat logical sessions/colors/progress, scoped persistent logs, and a FIFO Computer-use baton;

• per-session upper-right work bubbles for Computer Use active/waiting, CLI, folder exploration, and chat-response waiting, with optional detailed tools and explicitly public rationale;

• a separate token-protected Windows/Android Device View and manual-control URL;

• a click-through, screen-saver-level transparent desktop HUD with an 18×24 px AI needle pointer, animated virtual keyboard, input-active screen border, and optional AI focus rectangle without recording typed text;

• a center-lower operation brief showing the AI's user-visible task summary, current target, progress, and recent real tool execution log;

• a local media hub that receives and previews images, video, audio, 3D assets, and bundles generated by signed-in web AI clients or other MCP tools;

• connector permissions, active sessions, revocation, pairing-token copy, and local safe/agent/full policy controls;

• an owner-managed custom MCP connection center with encrypted None/Bearer/API-key/OAuth credentials, auto-reconnect, tool inventory, and a two-gate AI relay;

• Quick Tunnel, private-LAN, and stable Cloudflare Named Tunnel management.

• endpoint-preserving MCP-core restart plus Named Tunnel default start and automatic recovery;

• a hybrid IP mode that keeps public HTTPS connected while also listening on this PC's LAN IPv4 address.

The dashboard and desktop HUD distinguish the external-AI lifecycle explicitly:

• Not connected: the server is online but no external OAuth connector or live MCP session is detected;

• Pairing: an AI client has registered and is waiting for consent, the pairing token, or OAuth token exchange;

• Connected / idle: OAuth authorization and refresh credentials are valid and the connector is waiting for its next tool call;

• Live connection: real MCP transport activity was detected in the last 90 seconds.

An abandoned pairing indication expires after ten minutes and returns to Not connected. The launcher's own local OAuth verification clients are excluded from external connection status and counts.

Choose Start temporary HTTPS for a generated Quick Tunnel URL, or configure a stable domain in the Fixed domain section and choose Start fixed domain. The app creates the server and tunnel as background processes; quitting the app from its tray menu can either keep them running or stop them.

Enable Fixed domain → Hybrid IP mode when trusted devices on the same router must also reach the server. The MCP core listens on 0.0.0.0:8787, the launcher detects the preferred LAN IPv4, and the dashboard displays and copies http://LAN-IP:8787/mcp. The public HTTPS URL and OAuth resource stay unchanged, so remote AI connectors do not need to be registered again. Windows firewall and network-profile policy can still block another LAN device.

MCP-Remote-Control-App.cmd opens the same Electron app directly. Passing an existing command-line switch to MCP-Remote-Control-Launcher.cmd still opens the legacy PowerShell interface for automation compatibility.

If Quick Tunnel DNS propagation is delayed, the app keeps the server and tunnel running and reports the state in the activity stream. The Electron app can also be run with npm run app, tested with npm run app:smoke, or built as a portable Windows executable with npm run app:dist.

Related MCP server: hardened-terminal-mcp

Language

Use 한국어 / English in the dashboard header. The choice is saved locally and restored after the launcher restarts; the tray menu and owner-visible desktop HUD follow the same setting. The Android and iOS companions provide the same switch at the top of their owner screens. The Android authenticated live-view page also has its own Korean/English switch and remembers it in that browser.

The OAuth consent page keeps scripts, external resources, frames, and base-URL changes blocked in its CSP. It intentionally omits only form-action, because embedded AI-client browsers can otherwise reject the required same-server form post.

The desktop HUD now follows each tool call from tool_start through success or failure. For mouse and keyboard tools launched by Electron, the server emits the start event and waits 220 ms before applying Windows input. Even when start and completion arrive in one polling batch, LIVE motion remains visible for at least 0.7 seconds and the completed pointer or keyboard remains for 3.2 seconds. Late completions are matched by activity ID and cannot overwrite a newer operation. The small connection indicator stays visible while the server is online. Open Permissions → AI operation HUD preview to replay the mouse, click, and private-keyboard designs without changing desktop input.

The compact custom pointer is rendered in a click-through always-on-top overlay. It now uses an 18×24 CSS-pixel asymmetric AI needle shape with no permanent targeting ring, a small detached action label, and a brief click wave, keeping its perceived size close to the Windows pointer. Keyboard calls show a virtual keyboard with pressed-key motion; type_text uses a neutral animation derived only from the character count, while the actual text never reaches the renderer or audit file. A moving screen-edge signal is active only while mouse, keyboard, app, browser, or focus input is in progress. Screenshot, window-inspection, and focus calls paint the region the AI is currently viewing; Permissions → AI focus HUD can turn that rectangle off independently. The Windows worker opts into Per-Monitor DPI awareness, keeping full-screen captures and input coordinates aligned at 125%, 150%, and higher display scaling.

Permissions → Administrator app control starts a loopback-only elevated input helper after the PC owner manually accepts the Windows UAC prompt. While it is active, mouse, keyboard, and window-focus calls can reach ordinary applications that were already launched at high integrity. It is deliberately not a UAC bypass: the helper refuses the secure desktop, consent and credential prompts, sign-in UI, and Windows Security surfaces. It exits when the Electron launcher exits and can be stopped locally at any time. The MCP endpoint cannot start this helper; only the local dashboard can request elevation.

The center-lower message HUD combines two sources: automatic tool lifecycle records and summaries explicitly published through hud_status_update. The latter is for a concise action, plan, result, or safe decision rationale intended for the PC owner. It is not a chain-of-thought viewer: agents must never send hidden reasoning, credentials, typed private content, or raw sensitive data. Keyboard text remains excluded from both the HUD and audit file.

Each upper-right AI session card also has its own current-work bubble. Permissions → AI session work bubbles toggles the bubbles, while Show detailed tools and public rationale adds the latest tool name and only the owner-visible rationale explicitly supplied through hud_status_update.reasoning_summary. Hidden chain-of-thought is never requested, collected, or stored. Ended sessions remain available through AI work sessions → View logs, backed by their per-session persistent audit file.

Connect an AI client with the in-app wizard

The simplest route is to open Connection wizard in the Electron launcher and follow it from top to bottom:

1. Select Start default server and wait for HTTPS ENDPOINT READY.

2. Select Copy MCP URL. An internet-hosted AI client requires the public https://.../mcp endpoint; a private 192.168.x.x URL is only for trusted clients on the same LAN.

3. In the AI service or app, open its MCP, Connectors, or Tools settings, add a remote MCP server, and enter the copied URL. Any display name is valid; Remote MCP Control is recommended.

4. In the OAuth consent page, paste the value copied by Copy pairing token, choose the permissions to grant, and approve. Pasting all text from bootstrap-token.txt, including its final newline, is accepted because the server normalizes surrounding whitespace.

5. Enable Remote MCP Control in the AI conversation, copy the launcher's test prompt, and send it. The connection is complete when the launcher shows LIVE MCP CONNECTION and logs the system_info call.

The wizard reports server reachability, durable OAuth authorization, and a recent live MCP session separately. APPROVED · AUTO REFRESH with IDLE · READY is a healthy authorized connector waiting for its next tool call, not a broken connection.

The URL to register is:

https://YOUR-TUNNEL.trycloudflare.com/mcp

Do not register the root URL, /healthz, or the metadata URL. When the connector opens the OAuth authorization page, enter the pairing token stored in data\bootstrap-token.txt on this PC.

The legacy launcher menu remains available for command-line use and provides pairing-token copy, OAuth verification, provider-neutral connection guidance, status, URL copy, shutdown, local control-profile management, connector status/revocation, and live activity logs. The token is trimmed before copying so the final newline in bootstrap-token.txt cannot break authorization. Clear the clipboard after pasting the token.

powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -Start
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -CopyToken
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -Verify
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -Stop
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -SetProfile full
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -AddWorkspace C:\work\my-project
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -LoginAgent claude
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -Connections
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -WatchActivity
powershell.exe -ExecutionPolicy Bypass -File .\scripts\launcher.ps1 -RestartServer

Why the previous plugin connection failed

The first version exposed a custom /auth/exchange endpoint using a bootstrap secret and client_credentials. Standards-compatible remote MCP clients use OAuth 2.1 authorization code flow with PKCE; the bootstrap token is local owner consent, not a connector credential. The server now publishes protected-resource metadata, authorization-server metadata, a dynamic registration endpoint, an authorization page, PKCE token exchange, refresh-token rotation, registered-client Origin enforcement, and per-tool OAuth metadata. Discovery and registration accept syntactically valid HTTPS client origins without a provider-domain allowlist; subsequent browser requests are limited to the exact registered client and callback origins.

OAuth access tokens now last 30 days by default and refresh tokens 365 days. A refreshed access token remains authorized for an existing MCP session when it belongs to the same OAuth client. A changed Quick Tunnel URL is a new OAuth resource, however, and requires a new authorization; use a stable named tunnel to avoid that.

If an AI client reports tool disabled while the launcher's AI Connections page shows Authorized · 0 active sessions, the server and OAuth grant are still available. The request was blocked by the client's per-conversation tool state before it reached this PC. Refresh Remote MCP Control in that client's MCP/connector management screen and enable it again in the conversation. This reuses the existing OAuth grant and does not require the pairing token again. The remote server cannot force a client to keep a tool enabled in every conversation, so the UI reports authorization readiness separately from recent live sessions.

Custom MCP connections

Open AI connections → Custom MCP connections to save a Streamable HTTP MCP URL using no authentication, a Bearer token, an API-key header, or standards-compatible browser OAuth. The owner app keeps enabled upstreams connected, discovers their tools and input schemas, checks them with a heartbeat, and retries bounded reconnections. Remote URLs require HTTPS; private-network and loopback HTTP remain available for owner-controlled local services. Bounded non-secret configuration queries such as Supabase project_ref and features are supported, while credential-like query names remain blocked.

Credentials are encrypted with the current Windows account's secure storage and never returned to the renderer, status JSON, AI client, or activity log. AI access is off by default and requires both the connection card's AI tool relay switch and the connector's separate external_mcp permission. The relay exposes only custom_mcp_connection_list, custom_mcp_tool_list, and custom_mcp_tool_call; full endpoint paths and credentials are withheld. Keep the Electron owner app running because it owns the encrypted credentials and authenticated loopback broker. See the complete custom MCP guide.

Connector permissions and activity

The local OAuth consent page now lets you approve or leave unchecked each authority category:

• desktop/system viewing;

• desktop input and browser use;

• non-critical process stopping;

• configured local coding-agent background jobs;

• background-job output and stop;

• allowlisted CLI jobs.

• generated-media receipt and delivery for images, video, audio, 3D assets, and ZIP bundles.

• Android device viewing, Android input/app control, and Android shared-file transfer as three separate grants.

• approved project-workspace listing, reading, writing, and file delivery.

• owner-configured external MCP listing and tool relay, guarded separately by each connection's local exposure switch.

Viewing is required to establish a useful connector. The local control profile remains a second, machine-owner boundary: a connector cannot gain authority that the local profile denies. To reduce a connected AI's permissions later, use launcher option 17 to revoke its connector authorization, then reconnect and select the new permissions. Options 14 and 15 show recent or live activity; option 16 shows connector status, active sessions, granted categories, and token state without exposing token values.

Generated media relay

A connected agent should call media_transfer_capabilities first and select a route based on where the generated result is available. Completed assets appear in the managed data\media\assets inbox and on the Electron Media hub page. Raster images receive real thumbnails and can be returned to the connected multimodal agent as MCP image content through media_preview.

If a connector authorized on v0.2.6 or earlier does not have the new media grant, choose AI connections → Add media permission. This local-owner action applies the current full permission set to the existing access and refresh credentials and closes only stale MCP transports. The next tool call reconnects with the same OAuth grant, without another pairing-token prompt. To narrow authority instead, revoke the connector and select only the required categories on the OAuth consent page.

1. Signed-in-browser assets: a private asset URL that requires browser cookies cannot be retrieved by the server from the URL alone. Click Download in the signed-in browser on this PC, then call media_import_recent_download; optionally use name_contains to select the intended recent file.

2. Web-MCP output: when a tool returns a public or not-yet-expired signed HTTPS URL, call media_import_url immediately. Every redirect is DNS- and destination-checked, and signed query credentials are never stored in the audit trail or asset metadata.

3. Raw files without a usable URL: call media_upload_begin, sequential media_upload_chunk calls, then media_upload_complete. Upload ownership follows the OAuth connector across short MCP transports. After reconnecting, call media_upload_status and continue from next_chunk; retrying the immediately previous identical chunk or an already completed request is idempotent.

4. Project delivery: call media_export_to_workspace to copy the asset into an existing locally approved project directory. Existing files are never overwritten; the relay allocates a numeric suffix.

Supported formats include PNG/JPEG/WebP/GIF/AVIF and other raster assets; MP4/WebM/MOV/MKV video; MP3/WAV/OGG/M4A/FLAC audio; GLB/GLTF/OBJ/FBX/STL/USDZ/BLEND/PLY 3D assets; and ZIP bundles. The default asset limit is 512 MiB, decoded chunks are at most 512 KiB, and inline image previews are at most 20 MiB. Override the first two limits with MCP_MEDIA_MAX_BYTES and MCP_MEDIA_CHUNK_BYTES.

URL imports accept only credential-free HTTPS on port 443 and reject localhost, private or reserved networks, excess redirects, oversize responses, and declared-type/signature mismatches. Local import is limited to Downloads, Desktop, Documents, Pictures, Videos, browser asset staging, and locally approved workspaces. Chunk transfers enforce connector ownership, sequence, size, and optional SHA-256, preventing a second AI from splicing data into the same upload.

Mobile device bridge

Open the Electron Mobile devices page. Its connection center lists every currently visible ADB device, keeps a short redacted history of recently disconnected devices, and separates USB, wireless ADB, RSA approval, companion-app, Accessibility, and mobile-MCP states without exposing a full hardware serial. Select a card before installing or taking a screenshot; those owner actions are routed only to that explicit device even when several phones or tablets remain connected.

Android setup is one-time per trusted PC:

1. Connect the owner’s Android phone with a data-capable USB cable.

2. On the phone, enable Developer options, turn on USB debugging, unlock the phone, and approve this PC’s RSA fingerprint. See the official ADB guide.

3. Refresh Mobile devices, confirm that the card shows ADB AUTHORIZED, and select it. Use Add another device to keep the current device connected while onboarding another USB or wireless-ADB device.

4. Run Install app and test or View selected device. The launcher passes the selected redacted device ID through Electron to ADB, so another ready device cannot receive the operation accidentally.

5. In AI connections, grant only the needed categories: mobile_view, mobile_control, and/or mobile_files. An older connector can use Sync current full permissions without repeating OAuth; revoke and reconnect when narrowing its authority.

The Android tools never expose a general adb shell. Inputs are allowlisted, package names and HTTPS URLs are validated, and file access is confined to /sdcard/Download, /sdcard/DCIM, /sdcard/Pictures, and /sdcard/Movies. Touch, app, key, and URL operations require the local agent or full profile and an unlocked phone. PIN, password, pattern, biometrics, payment confirmation, credential prompts, protected screens, root, bootloader, install/uninstall, and app-private data are outside the bridge.

Android control uses a separate logical-session FIFO lease (mobile_control_status, mobile_control_acquire, mobile_control_release), so a second web chat cannot interleave phone actions. Screenshots and read-only inspection remain available while a lease is held. Full serials and typed text are omitted from audit logs.

The optional native Android companion in mobile/android also runs standalone without a PC. Version 0.10.1 bundles the pinned, checksum-verified official Linux ARM64 cloudflared runtime: the owner can start a temporary Quick Tunnel or configure a fixed Named Tunnel directly in the app. The resulting public HTTPS origin exposes the phone's OAuth-protected /mcp and token-protected /view routes without Internet router port forwarding. Its accessibility HUD shows the connected AI, action, focus, compact click pointer, private keyboard motion, and input-active border; an on-device button stops the tunnel, revokes every session, and rotates the token. Activity persists as redacted rotating NDJSON, and Android inputs use a separate session lease so multiple AIs and the live browser cannot interleave.

The iOS source in mobile/ios provides screen-awake settings, AI identity/HUD, persistent audit, opt-in LAN MCP, and an authenticated live view of the companion's own foreground window. Apple app sandboxing prevents an ordinary iOS app from overlaying, capturing, inspecting source code, or controlling arbitrary other apps or the full system. App-under-test UI automation requires a Mac, Xcode, signing, and XCUITest. This Windows build cannot compile, sign, or deploy the iOS target.

Tools

• Visual inspection: desktop_screenshot, desktop_region_screenshot, window_screenshot, screen_info, and desktop_security_status. Screenshot tools return actual MCP image/png content plus bounds metadata, while the security-status tool reports the input desktop, foreground target, and elevated-helper readiness without exposing credentials.

• Logical AI sessions: ai_session_register, ai_session_resume, ai_session_status, and ai_session_end.

• Desktop control: list_windows, launch_app, focus_window, type_text, send_hotkey, key_down, key_up, mouse_click, mouse_move, mouse_drag, mouse_down, mouse_up, mouse_scroll, and browser_open.

• User-visible status: hud_status_update publishes a safe task brief to the center-lower local HUD.

• Multi-agent coordination: desktop_control_status, desktop_control_acquire, and desktop_control_release.

• Background observability: system_info, system_status, process_list, process_details, service_list, and control_capabilities.

• Generated media: media_transfer_capabilities, media_list, media_info, media_preview, media_import_url, media_import_recent_download, media_import_local, media_upload_begin, media_upload_status, media_upload_chunk, media_upload_complete, and media_export_to_workspace.

• Android bridge: mobile_bridge_capabilities, mobile_device_list, mobile_device_info, mobile_screenshot, mobile_control_status, mobile_control_acquire, mobile_control_release, mobile_tap, mobile_swipe, mobile_type_text, mobile_keyevent, mobile_app_list, mobile_app_launch, mobile_app_stop, mobile_open_url, mobile_file_list, mobile_file_pull, and mobile_file_push.

• Project files: workspace_file_list, workspace_file_read, workspace_file_write, and workspace_file_download.

• Custom MCP relay: custom_mcp_connection_list, custom_mcp_tool_list, and custom_mcp_tool_call.

• Process control: process_stop for non-critical processes only. The MCP server and core Windows processes are protected.

• Agent jobs: agent_start, background_job_list, background_job_output, and background_job_stop for non-interactive Codex or Claude Code tasks.

• Direct allowlisted CLI jobs: cli_start, available only after the local full profile is enabled.

All tool calls are recorded in data\audit.ndjson. Registered work is also written to per-session and per-project journals under data\audit-scopes, and the launcher's two log selectors can reload either scope. Internal launcher polling is excluded. While agent_start or cli_start owns a workspace, created, modified, and deleted paths are also recorded without file contents; .git, node_modules, build outputs, and caches are ignored to control noise. Set -DisableInput on the launcher or server start script to disable desktop-input tools.

Parallel project sessions and Device View

Open the Electron AI work sessions page and choose Add project folder for each existing directory that an AI may use. Select Copy registration prompt beside a folder and paste it once into each AI conversation. That conversation calls ai_session_register and receives:

• a logical ai_session_id and distinct HUD color;

• one approved project root and a PC, Android, or iOS target;

• independent task/progress/tool state and scoped audit files;

• independent ownership in the desktop and Android input baton queues.

MCP does not expose the hosting product's conversation ID, so guessing from a connection name is not reliable. Each conversation must include its returned ai_session_id in later calls. A one-time private resume_token supports explicit recovery through ai_session_resume; the launcher, session list, and audit files never reveal it. If several logical sessions share one OAuth connector and omit the ID, file, input, and background-job tools return an ambiguity error instead of attaching work to the wrong chat.

The top-right PC HUD lists active PC sessions as color-coded cards and overlaps the fifth and later cards to preserve screen space. Android-targeted events are filtered from the PC overlay and relayed through an ADB-loopback-only bridge to the phone's own accessibility HUD, including the AI name, action, tap, swipe, and private keyboard visualization.

The server also starts a separate, token-protected Device View service on port 8791. Open or copy it from Live screen → Device View to view and manually control the current Windows desktop or an approved Android device. It supports click/tap, pointer drag/swipe, wheel scrolling, text, hotkeys, held key/button down and up, and Android Back/Home/Recents. This service is separate from MCP/OAuth. It rejects unauthenticated API requests; Live screen → Reissue control link immediately revokes an exposed or no-longer-shared link. AI-requested project downloads use short-lived, single-file tickets rather than disclosing the manual-control token. The local URL is http://127.0.0.1:8791; use the LAN URL only on a trusted private network or VPN, never through direct Internet port forwarding.

Multi-agent coordination

All real mouse, keyboard, window-focus, app-launch, and browser-open calls enter one explicit FIFO baton queue. When the owner releases or expires, the first waiter receives the lease immediately; retry timing cannot reorder the queue. For a multi-step desktop workflow, an agent should acquire a lease before the first input and release it in finally after the last input:

1. Call desktop_control_acquire with a short purpose and TTL.

2. Perform the related visual checks and input calls. Screenshot and other read-only tools remain concurrent, even while the lease is held.

3. Call desktop_control_release. The lease spans any short-lived MCP transports that a client may create for individual tool calls and expires automatically after at most ten minutes.

For registered work, the lease owner is the logical ai_session_id, not a transient MCP transport or the entire OAuth connector. Multiple web chats using one connector therefore wait independently while surviving short-lived per-call transports without reauthentication. Screenshots, files, and read-only checks remain concurrent. key_down and mouse_down holds are released by the matching up call and are also fail-safe released on lease expiry, session end, or server shutdown. Configured coding-agent and allowlisted CLI background jobs reserve their normalized working directory; use separate Git worktrees when concurrent edits are intentional.

Android input has an independent lease with the same connector-stable ownership and expiry behavior. Holding the desktop lease does not unnecessarily block a different AI from observing Android, while holding the Android lease prevents touch/app/key operations from interleaving on the phone.

Local control profiles

The public URL is protected by OAuth, but the machine owner still controls the maximum authority available through data\control-policy.json:

• safe: read-only system, screen, window, process, service, and existing-media inspection.

• agent (default): safe inspection plus media receipt/export, desktop input, browser/app launching, non-critical process stopping, and constrained Codex/Claude jobs.

• full: adds cli_start for the locally allowlisted program aliases only.

Use launcher options 8–12, or run scripts\control-profile.ps1. The policy restricts job working directories to allowed_workspaces, limits concurrent jobs and runtime, and lists every executable alias. It intentionally does not accept arbitrary shell/PowerShell command strings and rejects Codex/Claude dangerous permission-bypass flags. To make another project available to an agent, add it locally through option 12; do not weaken the workspace restriction by exposing a broad drive root.

Codex and Claude must already be authenticated on this PC. The launcher’s option 13 (or -LoginAgent codex / -LoginAgent claude) opens the provider’s normal interactive login flow in a visible terminal. This server does not transmit provider credentials through the MCP endpoint.

Manual operation

Local start:

powershell.exe -ExecutionPolicy Bypass -File .\scripts\start.ps1 -PublicBaseUrl http://127.0.0.1:8787

LAN start (the Windows firewall rule requires an elevated PowerShell):

powershell.exe -ExecutionPolicy Bypass -File .\scripts\start.ps1 -PublicBaseUrl http://LAN-IP:8787
powershell.exe -ExecutionPolicy Bypass -File .\scripts\install-firewall.ps1

The LAN MCP URL is http://LAN-IP:8787/mcp. LAN HTTP is intended for a trusted private network; use the public HTTPS launcher or a named/private tunnel for Internet access.

Manual legacy pairing for clients that do not use the OAuth flow remains available:

powershell.exe -ExecutionPolicy Bypass -File .\scripts\pair.ps1 -BaseUrl https://YOUR-TUNNEL.trycloudflare.com -ClientName my-laptop

The token is written to data\client-my-laptop.token. Never share data\bootstrap-token.txt or access-token files.

Verification

node .\scripts\verify-oauth.mjs https://YOUR-TUNNEL.trycloudflare.com
node .\scripts\verify.mjs https://YOUR-TUNNEL.trycloudflare.com
npm run verify:hud

To verify real screen PNG delivery, resumable media upload/preview, and two independent MCP sessions contending for the desktop lease:

$env:VERIFY_SCREENSHOT = '1'
$env:VERIFY_MEDIA = '1'
$env:VERIFY_COORDINATION = '1'
$env:VERIFY_ANDROID = '1'
node .\scripts\verify-oauth.mjs https://YOUR-TUNNEL.example.com
Remove-Item Env:VERIFY_SCREENSHOT, Env:VERIFY_MEDIA, Env:VERIFY_COORDINATION, Env:VERIFY_ANDROID

The first command exercises the same OAuth + PKCE flow used by the connector. With VERIFY_MEDIA=1, it leaves one 1×1 PNG in the managed inbox after verifying transfer resume, SHA-256, and real MCP image content. VERIFY_ANDROID=1 requires an owner-authorized USB-debugging device and verifies device metadata, a real PNG screen response, app and Download listing, the connector-owned mobile lease, one safe control action, and lease release through the public MCP URL. The second command checks the legacy pairing flow and MCP tool calls. verify:hud invokes screen_info and moves the cursor to its existing coordinates, allowing the real start/completion/auto-hide HUD lifecycle to be checked without clicking or typing.

The administrator helper is intentionally not started by automated tests because doing so displays a Windows security consent request. Verify it manually from Permissions → Administrator app control: approve once locally, confirm ADMIN READY, test against a harmless elevated app, then stop the helper. Never use the test to approve UAC, enter credentials, or interact with Windows Security.

If the authorization page accepts the token but the AI client does not finish linking, keep the same launcher session alive and retry from the current /mcp URL. Do not reuse a URL from an earlier Quick Tunnel session. The launcher audit file records oauth_authorization_approved and oauth_token_issued events without recording token values.

Tunnel behavior

The Electron Start temporary HTTPS button and legacy launcher option 1 use Cloudflare Quick Tunnel. The generated hostname is temporary and changes when the tunnel restarts.

For a stable URL, open the Electron Fixed domain page. It checks cloudflared and login state, can open the Cloudflare browser login, create a uniquely named locally managed tunnel, add the DNS route, and write a local ingress configuration that maps the hostname to 127.0.0.1:8787. Existing remote-managed tunnel URLs and tokens can still be registered manually; those tokens are encrypted with the current Windows user's secure storage. Use a simple unique name such as remote-mcp-admin-pc (English letters, numbers, and hyphens). The hostname must be under a domain active in the same Cloudflare account, such as https://mcp.example.com; existing DNS records are never overwritten. Once configured, Named Tunnel becomes the default start mode and is automatically recovered when the launcher starts. Preserve-address restart restarts only the MCP core while leaving the tunnel URL and OAuth resource unchanged. The resulting https://your-hostname/mcp URL remains unchanged across app restarts.

Option 18 provides the current private-LAN address as http://LAN-IP:8787/mcp; it remains stable while DHCP keeps the same IP and is suitable for trusted devices on that LAN after running scripts\install-firewall.ps1 as Administrator. It is not HTTPS and is not reachable by an internet-hosted AI connector. Use a named HTTPS tunnel for remote access.

The Electron hybrid IP mode keeps that private address active alongside the existing Quick or Named HTTPS tunnel. 192.168.x.x and similar private addresses are never directly reachable from an internet-hosted AI service. A client-specific private ingress may also work when it preserves HTTPS, OAuth metadata, and authorization headers, but it is separate from this launcher's public endpoint.

Leerness Project Harness

이 프로젝트는 Leerness v1.36.161 하네스를 사용합니다. AI 에이전트는 작업 전 leerness handoff로 컨텍스트를 적재하고, 작업 후 leerness check/leerness audit/leerness session close를 수행해야 합니다.

정체성 — AI 에이전트 운영 레이어 (UR-0030)

Leerness 는 실행기/코딩 에이전트가 아니라, 어떤 AI 코딩 에이전트(Claude Code · Codex · Cursor · Goose 등) 위에도 얹는 범용 운영 레이어입니다. 5개 공통 계층을 제공합니다:

• 기억(Memory) — 프로젝트 상태/결정/진행을 .harness/ 에 영속화

• 정책(Policy) — 8단계 권한 등급 + enforce (read-only→publish), MCP 호출 게이트

• 인수인계(Handoff) — 에이전트 간 컨텍스트 표준 전달 + get_project_context 1콜 온보딩

• 검증(Verification) — 근거 기반 완료 검증으로 허위 완료 감지 (권고; CI 게이트 필수화 시 차단)

• 감사(Audit) — drift/idempotency/secret/encoding 자동 감사 (self-heal: drift·idempotency --auto-fix, encoding --apply; secret 은 감지 전용)

AGENTS.md(정적 지침)을 대체하지 않고 보완합니다 — 정적 규칙은 AGENTS.md, 동적 상태·검증·인수인계는 leerness. 정체성 조회: leerness about (MCP leerness_about).

Core Commands

leerness handoff .            # 세션 시작 컨텍스트 자동 로드
leerness status .             # 설치 상태
leerness verify .             # 필수 파일 검증
leerness audit .              # 일관성·계획-진행 정렬 감사
leerness scan secrets .       # 시크릿 패턴 스캔
leerness encoding check .     # UTF-8 / BOM / NUL / .bat 인코딩 검사
leerness lazy detect .        # 게으름 방지 자동 평가
leerness memory search "키"   # 결정/이력 검색
leerness session close .      # 세션 종료 + handoff 자동 작성
leerness update .             # 자동 버전 감지 + 마이그레이션

Memory Surface CRUD (5 surfaces × add/list/drop)

# Tasks
leerness task add "T-9999 작업 제목"
leerness task list --json
# Decisions
leerness decision add "결정 제목" --reason "이유"
leerness decision list --query "키워드"   # 1.9.139
# Rules (영구 자연어 룰)
leerness rule add "매 commit마다 changelog 갱신" --trigger every-commit
leerness rule list
# Plan (milestones)
leerness plan add "M-XXXX 계획" --next "다음 단계"
leerness plan list
# Lessons (영구 교훈)
leerness lesson save "교훈 본문" --tag perf
leerness lesson list --query "키워드"     # 1.9.139
# DELETE → RESTORE (1.9.126~128)
leerness memory archive list . --query "키워드"   # 1.9.138
leerness memory restore decision <date|title>

MCP server (외부 AI 통합)

Leerness v1.36.161는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 89개 도구를 노출:

// 카테고리별
// • Core: handoff / drift_check / audit / health / verify_claim / contract_verify
// • Memory READ:  task_list / decision_list / lesson_list / plan_list / rule_list / memory_status
// • Memory WRITE: task_add / decision_add / lesson_save / plan_add / rule_add
// • Memory DELETE: task_drop / decision_drop / lesson_drop / plan_remove / rule_remove
// • Skill: skill_match / skill_list / skill_search / skill_info / skill_suggest
// • Insight: lessons / lessons_auto / brainstorm / retro / benchmark / lazy_detect
// • Workflow: session_close / agents_list / task_export / env_check / usage_stats / reuse_map / whats_new

// MCP server 실행: leerness mcp serve
// tools/list 응답: 89 도구

Autonomous mode (자율 모드)

<<autonomous-loop-dynamic>> 신호만 보내면 AI가:

1. 다음 라운드 후보 선정 → 2) 코드 변경 → 3) 회귀 테스트 갱신 → 4) 전체 e2e 스위트 통과 → 5) npm publish + git tag → 6) main push → 7) session close → 8) 다음 라운드 예약.

현재 누적: v1.9.x → 1.36.161 릴리스 태그 이력 (수백 라운드) · _reports/는 비공개 보존.

성능 가이드

• leerness handoff . — 평균 ~1.5s (캐시 워밍업 후 ~0.6s)

• leerness memory status --json — 평균 ~250ms

• leerness task list --json — 평균 ~200ms

• leerness drift check --json — 평균 ~400ms

• MCP tools/list 응답 — 평균 ~150ms

• usage-stats / lessons / listAllSkills 모두 메모리 캐싱

빠른 시작

# 1. 설치 (글로벌)
npm install -g leerness

# 2. 프로젝트에 하네스 설치
cd my-project && leerness init . --yes --skills recommended

# 3. AI 세션 시작 시
leerness handoff .            # 컨텍스트 자동 로드

# 4. 세션 종료 시
leerness session close .      # 9 카테고리 + 룰 검증 + 다음 라운드 추천

# 5. release 자동화 (main 자동 push 포함)
leerness release pack --close --auto-main-push

Planning Files

• .harness/plan.md: 전체 목표, milestone, 제외/드랍 범위

• .harness/progress-tracker.md: 요청 단위 상태와 증거

• .harness/current-state.md: 지금 이어서 할 작업

• .harness/session-handoff.md: 다음 세션 인수인계 (자동 작성)

• .harness/lessons.md / decisions.md / rules.md: 영구 메모리 (5 surface)

Last synced by Leerness v1.36.161: 2026-08-26