yonder
Control remote Windows PCs from your local AI host (Codex / MCP) via a zero-runtime PowerShell 5.1 client.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/shuaixunw--yonder)HTML
<a href="/listings/shuaixunw--yonder"><img src="/api/listings/shuaixunw--yonder/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
5-Minute Local Trial (Loopback Mode)
Try Yonder on a single Windows machine first without setting up Tailscale:
1. Install dependencies, initialize the local state DB, and create a pairing code (using `loopback_test` on `127.0.0.1:8731`):
cd hub npm ci cd .. node hub/src/cli.mjs --config hub/hub.json init node hub/src/cli.mjs --config hub/hub.json pair-create --name local-test --ttl-sec 600
2. Start the Hub and pair/run the client in another PowerShell window:
# Terminal 1: Start Hub (or let Codex launch it via MCP) node hub/src/server.mjs --config hub/hub.json # Terminal 2: Pair and run local test client powershell.exe -NoProfile -File .\client\client.ps1 -Mode Pair -Server "http://127.0.0.1:8731" -Name "local-test" -AllowedRoots "D:\diag" -ExecutionMode "read_only" powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
---
Cross-Machine Setup
1. Configure Hub & Generate a Pairing Code
Copy `hub/hub.example.json` to `hub/hub.json`. Set `transportMode` to `encrypted_private`, set `listen.host` to your machine's private overlay IP (e.g., Tailscale `100.64.x.x`), and set `stateDir` to a local directory outside the repository and cloud-sync folders.
With the Hub stopped, initialize and generate a pairing code:
node hub/src/cli.mjs --config hub/hub.json init node hub/src/cli.mjs --config hub/hub.json pair-create --name game-pc --ttl-sec 600
2. Register the MCP Server in Your AI Host
Example Codex configuration (`stdout` is reserved for MCP; logs go to `stderr`):
[mcp_servers.yonder] command = "C:/Program Files/nodejs/node.exe" args = [ "<path-to-yonder>/hub/src/server.mjs", "--config", "<path-to-yonder>/hub/hub.json" ] cwd = "<path-to-yonder>" startup_timeout_sec = 15 tool_timeout_sec = 30 default_tools_approval_mode = "prompt" enabled_tools = [ "list_machines", "system_info", "list_dir", "read_text", "run_powershell", "get_command", "cancel_command" ] [mcp_servers.yonder.tools.run_powershell] approval_mode = "prompt" [mcp_servers.yonder.tools.cancel_command] approval_mode = "prompt"
3. Pair & Run on the Remote Windows PC
Copy `client/client.ps1` to the remote Windows PC (no Node.js needed) and run:
# 1) Pair (enter the pairing code when prompted) # Use -ExecutionMode trusted_powershell to allow command execution, or read_only for file/system inspection only powershell.exe -NoProfile -File .\client\client.ps1 -Mode Pair -Server "http://<CONTROL_PC_PRIVATE_IP>:8731" -Name "game-pc" -AllowedRoots "D:\work" -ExecutionMode "trusted_powershell" # 2) Start polling for tasks powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
The client stores its token via Windows DPAPI at `%LOCALAPPDATA%\RemotePcClient\<hubId>\<machineId>\credential.dat`. `client.json` does not contain plaintext tokens.
4. Revoke a Machine
Stop the Hub and run:
node hub/src/cli.mjs --config hub/hub.json revoke --machine game-pc
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 200 lines
- # Yonder
- **English** | [中文](README.zh-CN.md)
- **Control remote Windows PCs from your local AI host (such as Codex or any MCP-compatible client) — with zero AI clients, Node.js, or Python required on the remote machines.**
- Yonder uses a **Local MCP Hub + Remote Native PowerShell Long-Polling Client** architecture. All AI reasoning, context, and orchestration stay on your primary machine, while each remote Windows PC only runs a lightweight PowerShell 5.1 script (`client.ps1`) that polls outbound for tasks.
- 
- ---
- ## Key Features
- - **Zero Extra Runtime on Remote PCs**: Remote machines only need built-in Windows PowerShell 5.1 and .NET Framework — no Codex, Antigravity, Node.js, or Python installation required.
- - **Outbound-Only Connections**: Remote clients initiate HTTP long-polling requests outbound to the Hub. No listening ports need to be opened on controlled machines.
- - **No Dedicated Hosting Server Needed**: The Hub runs directly on your local control machine. For cross-network or remote access, pair it with an encrypted overlay network like [Tailscale](https://tailscale.com/).
- - **Explicit Security Boundaries**:
- - File tools are restricted to an `allowedRoots` allowlist and block reading binary dumps/executables (`.dmp`, `.sys`, `.exe`, `.dll`).
- - Defaults to `read_only` mode. PowerShell execution is only enabled when the remote machine explicitly opts into `-ExecutionMode trusted_powershell`, running under the current standard user account (no automatic elevation).
- - Spawned child processes are managed via Windows Job Objects.
- - **Credential & Transport Safety**:
- - One-time pairing codes are generated via the local Hub CLI. Clients store tokens encrypted with Windows DPAPI (`CurrentUser`), separate from `client.json`, while the Hub stores only token hashes.
- - Cross-machine deployments enforce `encrypted_private` mode and forbid binding to `0.0.0.0`.
- - **Idempotent & Resilient Task Execution**: Supports `requestId` idempotency, single active task slot per machine, pre-execution ACK, SQLite state persistence, async polling (`get_command`), and cancellation (`cancel_command`).
- ---
- ## Architecture
- ```mermaid
- flowchart LR
- AI["Local AI Host (e.g. Codex)"] -->|"Local MCP stdio"| Hub["Yonder Hub (Node.js)"]
- Hub --> DB[("Local SQLite State")]
- C1["Remote Windows A (client.ps1)"] -->|"HTTP Long-Polling (Encrypted Private Net)"| Hub
- C2["Remote Windows B (client.ps1)"] -->|"HTTP Long-Polling (Encrypted Private Net)"| Hub
- CLI["Local Admin CLI (cli.mjs)"] -->|"Pair / Revoke (Hub Stopped)"| DB
- ```
- - **Control Hub (`hub/`)**: Single Node.js process hosting the MCP tool adapter, task state machine, SQLite persistence, and device HTTP endpoints.
- - **Remote Client (`client/client.ps1`)**: Runs on each controlled Windows machine to enforce local policy, persist execution records, manage child processes, and report results.
- ---
- ## MCP Tools
- The Hub exposes 7 tools to your AI host:
- | Tool | Description |
- |---|---|
- | `list_machines` | List paired machines, online status, execution mode, and active tasks |
- | `system_info` | Retrieve current user, OS info, and client capabilities of a paired machine |
- | `list_dir` | List entries within an `allowedRoots` directory |
- | `read_text` | Paginated text file reader (`utf8`, `utf16le`, `utf16be`, `gb18030`, or `auto`) |
- | `run_powershell` | Run a PowerShell command on a `trusted_powershell` machine (returns immediately for short tasks or `commandId` for long tasks) |
- | `get_command` | Query task status and output by `commandId` or `requestId` (works even if the machine later goes offline) |
- | `cancel_command` | Request cancellation of an active command |
- ---
- ## Requirements
- - **Control Machine (Hub)**: Windows, Node.js `>= 22.13`
- - **Remote Machine (Client)**: 64-bit Windows, Windows PowerShell 5.1
- - **Cross-Machine Network**: For machines outside loopback, install an encrypted overlay network such as [Tailscale](https://tailscale.com/) on both ends and use the assigned private IP.
- ---
- ## Quick Start
- ### 5-Minute Local Trial (Loopback Mode)
- Try Yonder on a single Windows machine first without setting up Tailscale:
- 1. Install dependencies, initialize the local state DB, and create a pairing code (using `loopback_test` on `127.0.0.1:8731`):
- ```powershell
- cd hub
- npm ci
- cd ..
- node hub/src/cli.mjs --config hub/hub.json init
- node hub/src/cli.mjs --config hub/hub.json pair-create --name local-test --ttl-sec 600
- ```
- 2. Start the Hub and pair/run the client in another PowerShell window:
- ```powershell
- # Terminal 1: Start Hub (or let Codex launch it via MCP)
- node hub/src/server.mjs --config hub/hub.json
- # Terminal 2: Pair and run local test client
- powershell.exe -NoProfile -File .\client\client.ps1 -Mode Pair -Server "http://127.0.0.1:8731" -Name "local-test" -AllowedRoots "D:\diag" -ExecutionMode "read_only"
- powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
- ```
- ---
- ### Cross-Machine Setup
- #### 1. Configure Hub & Generate a Pairing Code
- Copy `hub/hub.example.json` to `hub/hub.json`. Set `transportMode` to `encrypted_private`, set `listen.host` to your machine's private overlay IP (e.g., Tailscale `100.64.x.x`), and set `stateDir` to a local directory outside the repository and cloud-sync folders.
- With the Hub stopped, initialize and generate a pairing code:
- ```powershell
- node hub/src/cli.mjs --config hub/hub.json init
- node hub/src/cli.mjs --config hub/hub.json pair-create --name game-pc --ttl-sec 600
- ```
- #### 2. Register the MCP Server in Your AI Host
- Example Codex configuration (`stdout` is reserved for MCP; logs go to `stderr`):
- ```toml
- [mcp_servers.yonder]
- command = "C:/Program Files/nodejs/node.exe"
- args = [
- "<path-to-yonder>/hub/src/server.mjs",
- "--config",
- "<path-to-yonder>/hub/hub.json"
- ]
- cwd = "<path-to-yonder>"
- startup_timeout_sec = 15
- tool_timeout_sec = 30
- default_tools_approval_mode = "prompt"
- enabled_tools = [
- "list_machines",
- "system_info",
- "list_dir",
- "read_text",
- "run_powershell",
- "get_command",
- "cancel_command"
- ]
- [mcp_servers.yonder.tools.run_powershell]
- approval_mode = "prompt"
- [mcp_servers.yonder.tools.cancel_command]
- approval_mode = "prompt"
- ```
- #### 3. Pair & Run on the Remote Windows PC
- Copy `client/client.ps1` to the remote Windows PC (no Node.js needed) and run:
- ```powershell
- # 1) Pair (enter the pairing code when prompted)
- # Use -ExecutionMode trusted_powershell to allow command execution, or read_only for file/system inspection only
- powershell.exe -NoProfile -File .\client\client.ps1 -Mode Pair -Server "http://<CONTROL_PC_PRIVATE_IP>:8731" -Name "game-pc" -AllowedRoots "D:\work" -ExecutionMode "trusted_powershell"
- # 2) Start polling for tasks
- powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
- ```
- The client stores its token via Windows DPAPI at `%LOCALAPPDATA%\RemotePcClient\<hubId>\<machineId>\credential.dat`. `client.json` does not contain plaintext tokens.
- #### 4. Revoke a Machine
- Stop the Hub and run:
- ```powershell
- node hub/src/cli.mjs --config hub/hub.json revoke --machine game-pc
- ```
- ---
- ## Project Structure
- ```text
- yonder/
- ├── .agents/skills/remote-pc/ # Skill instructions for AI hosts
- ├── client/ # Windows PowerShell 5.1 client & example config
- ├── docs/ # Installation, acceptance, and troubleshooting guides
- ├── hub/ # Node.js MCP Hub server & local admin CLI
- ├── samples/ # Minimal diagnostic sample script
- ├── schemas/ # JSON Schemas for config and results
- └── tests/ # Protocol and Windows client test suites
- ```
- ---
- ## Tests
- Run the test suite from `hub/`:
- ```powershell
- cd hub
- npm test
- ```
- ---
- ## Documentation & License
- - [Installation & Pairing Guide (zh-CN)](docs/install.md)
- - [Acceptance Checklist (zh-CN)](docs/acceptance.md)
- - [Troubleshooting (zh-CN)](docs/troubleshooting.md)
- - License: [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.