WinBridge AI

English | 中文

Operate a Windows computer from a Mac-side AI.

WinBridge AI is a local-first operation layer for controlling Windows machines from a Mac. It gives a Mac-side AI a practical execution surface on Windows: run commands and scripts, inspect the environment, move files, launch processes, install software, capture screenshots, collect logs, and close the loop through visual or command output. Windows does not need an AI runtime or development setup up front. Start the bridge on the Mac, run the generated one-line command on Windows, then operate the machine from the Mac control plane.

Status

This repository is the extracted product seed from GitMemo's Windows control and build helper. The current version is useful for trusted-LAN operation, development, debugging, build, QA, and verification workflows. It is not yet a hardened remote-access product.

Quick Start

Install the CLI on the control computer (Mac, Linux, or Windows with Node.js 18+):

npm install -g ai-windows-bridge

Start WinBridge AI:

winbridge start

The same command works from a checkout with npm start.

The terminal prints a six-digit pairing code, the control console URL, and one or more Windows pairing URLs, for example:

Pairing code: 123456
http://127.0.0.1:47832/console?code=123456
http://192.168.0.110:47832/?code=123456

On the Mac, open the control console:

http://127.0.0.1:47832/console

The console is where you can see connected LAN agents, screenshots, messages, jobs, uploaded logs, and command output. You can also send a message to the Windows page, run PowerShell, request screenshots, and launch task templates.

On the Windows computer:

1. Open the printed URL in a Windows browser. If you opened the base address, enter the six-digit pairing code.
2. The first visible task is Copy and run this Agent command.
3. Click Copy Agent Command.
4. Paste it into Windows PowerShell and run it.
5. Keep that PowerShell window open while the Mac controls Windows.
6. Use Send a message to Mac if you need to report something from Windows.

That page also provides optional commands for:

• starting the polling Windows agent without SSH;
• optionally bootstrapping OpenSSH Server;
• optionally installing a Windows build environment.

Once the Windows agent says it is connected, return to the Mac console or use the CLI:

winbridge status
winbridge run "hostname; whoami"
winbridge screenshot

In other words, the normal flow is still:

Mac starts server -> Mac opens /console -> Windows opens pairing URL -> Windows copies/runs agent command -> Mac controls Windows

Runtime Data

When installed from npm, runtime data is stored outside the package so global installs remain writable:

• macOS/Linux: ~/.local/state/winbridge/
• Windows: %LOCALAPPDATA%\winbridge\
• state and logs: <data-dir>/state/state.json
• pairing token: <data-dir>/state/pairing-token
• screenshots: <data-dir>/state/screenshots/
• files served to Windows: <data-dir>/artifacts/

Use winbridge start --data-dir <path> or WINBRIDGE_DATA_DIR to choose a different root. WINBRIDGE_STATE_DIR and WINBRIDGE_ARTIFACTS_DIR remain available for separate overrides.

Drop an installer into <data-dir>/artifacts/, then use Install Latest Artifact from the web console or run:

winbridge install-artifact

Environment Variables

• WINBRIDGE_PORT: server port, default 47832
• WINBRIDGE_HOST: listen address, default 0.0.0.0
• WINBRIDGE_DATA_DIR: runtime data root
• WINBRIDGE_STATE_DIR: custom state directory
• WINBRIDGE_ARTIFACTS_DIR: custom artifact directory
• WINBRIDGE_SSH_KEY: custom SSH private key path
• WINBRIDGE_PAIRING_CODE: fixed six-digit browser pairing code
• WINBRIDGE_AUTH_REQUIRED=1: require token checks for the web console, API, and Windows agent callbacks
• WINBRIDGE_AUTH=token: alternative way to require token checks
• WINBRIDGE_PAIRING_TOKEN: provide a fixed token and enable token checks
• WINBRIDGE_AUTH_DISABLED=1: force token checks off, even if another auth variable is present

Product Shape

WinBridge AI is meant to become a general Mac-to-Windows AI operation layer. The core idea is broader than build automation: once a Windows machine is connected, the Mac-side AI should be able to do anything that the current Windows user, PowerShell/scripts, files, processes, installed tools, and screen feedback allow.

Examples:

• execute Windows commands from AI tools;
• inspect system state, environment variables, files, processes, and logs;
• upload, download, create, edit, and delete files when permitted;
• launch apps, installers, tests, scripts, and diagnostic tools;
• capture screenshots so the AI can reason about visible Windows state;
• install software or artifacts as one use case, not the whole product;
• run build, QA, reproduction, repair, and operations templates;
• eventually expose MCP tools for Codex, Claude, Cursor, and other agents.

The boundary is the Windows permissions and automation surface available to the connected agent. WinBridge AI should not be described as a single-purpose build or installer tool; build and installation are just examples of operating Windows from the Mac.

Security Model

WinBridge AI binds to 0.0.0.0 so Windows machines on the LAN can reach it. Authentication is enabled by default. Users pair with a six-digit code; the server exchanges it for an HttpOnly browser session while CLI, API, and Windows agent requests continue to use a generated strong token internally. Incorrect pairing attempts are rate-limited. To explicitly disable authentication on an isolated trusted network:

winbridge start --auth none

Treat the pairing code and pairing URL as sensitive. Run WinBridge AI only on trusted networks and stop the server when work is finished.

Read docs/security.md before exposing this beyond a trusted LAN.

Website

The standalone product website lives in website/. It is currently a static site and can be opened directly:

open website/index.html