# WinBridge AI

[English](README.md) | [中文](README_CN.md)

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+):

```bash
npm install -g ai-windows-bridge
```

Start WinBridge AI:

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

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

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

```bash
winbridge status
winbridge run "hostname; whoami"
winbridge screenshot
```

In other words, the normal flow is still:

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

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

```bash
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](docs/security.md) before exposing this beyond a trusted
LAN.

## Website

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

```bash
open website/index.html
```
