Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shuaixunw--yonder/badge.svg)](/listings/shuaixunw--yonder)

HTML

<a href="/listings/shuaixunw--yonder"><img src="/api/listings/shuaixunw--yonder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
  1. # Yonder
  2. **English** | [中文](README.zh-CN.md)
  3. **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.**
  4. 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.
  5. ![Yonder Demo](docs/assets/demo.gif)
  6. ---
  7. ## Key Features
  8. - **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.
  9. - **Outbound-Only Connections**: Remote clients initiate HTTP long-polling requests outbound to the Hub. No listening ports need to be opened on controlled machines.
  10. - **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/).
  11. - **Explicit Security Boundaries**:
  12. - File tools are restricted to an `allowedRoots` allowlist and block reading binary dumps/executables (`.dmp`, `.sys`, `.exe`, `.dll`).
  13. - 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).
  14. - Spawned child processes are managed via Windows Job Objects.
  15. - **Credential & Transport Safety**:
  16. - 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.
  17. - Cross-machine deployments enforce `encrypted_private` mode and forbid binding to `0.0.0.0`.
  18. - **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`).
  19. ---
  20. ## Architecture
  21. ```mermaid
  22. flowchart LR
  23. AI["Local AI Host (e.g. Codex)"] -->|"Local MCP stdio"| Hub["Yonder Hub (Node.js)"]
  24. Hub --> DB[("Local SQLite State")]
  25. C1["Remote Windows A (client.ps1)"] -->|"HTTP Long-Polling (Encrypted Private Net)"| Hub
  26. C2["Remote Windows B (client.ps1)"] -->|"HTTP Long-Polling (Encrypted Private Net)"| Hub
  27. CLI["Local Admin CLI (cli.mjs)"] -->|"Pair / Revoke (Hub Stopped)"| DB
  28. ```
  29. - **Control Hub (`hub/`)**: Single Node.js process hosting the MCP tool adapter, task state machine, SQLite persistence, and device HTTP endpoints.
  30. - **Remote Client (`client/client.ps1`)**: Runs on each controlled Windows machine to enforce local policy, persist execution records, manage child processes, and report results.
  31. ---
  32. ## MCP Tools
  33. The Hub exposes 7 tools to your AI host:
  34. | Tool | Description |
  35. |---|---|
  36. | `list_machines` | List paired machines, online status, execution mode, and active tasks |
  37. | `system_info` | Retrieve current user, OS info, and client capabilities of a paired machine |
  38. | `list_dir` | List entries within an `allowedRoots` directory |
  39. | `read_text` | Paginated text file reader (`utf8`, `utf16le`, `utf16be`, `gb18030`, or `auto`) |
  40. | `run_powershell` | Run a PowerShell command on a `trusted_powershell` machine (returns immediately for short tasks or `commandId` for long tasks) |
  41. | `get_command` | Query task status and output by `commandId` or `requestId` (works even if the machine later goes offline) |
  42. | `cancel_command` | Request cancellation of an active command |
  43. ---
  44. ## Requirements
  45. - **Control Machine (Hub)**: Windows, Node.js `>= 22.13`
  46. - **Remote Machine (Client)**: 64-bit Windows, Windows PowerShell 5.1
  47. - **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.
  48. ---
  49. ## Quick Start
  50. ### 5-Minute Local Trial (Loopback Mode)
  51. Try Yonder on a single Windows machine first without setting up Tailscale:
  52. 1. Install dependencies, initialize the local state DB, and create a pairing code (using `loopback_test` on `127.0.0.1:8731`):
  53. ```powershell
  54. cd hub
  55. npm ci
  56. cd ..
  57. node hub/src/cli.mjs --config hub/hub.json init
  58. node hub/src/cli.mjs --config hub/hub.json pair-create --name local-test --ttl-sec 600
  59. ```
  60. 2. Start the Hub and pair/run the client in another PowerShell window:
  61. ```powershell
  62. # Terminal 1: Start Hub (or let Codex launch it via MCP)
  63. node hub/src/server.mjs --config hub/hub.json
  64. # Terminal 2: Pair and run local test client
  65. 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"
  66. powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
  67. ```
  68. ---
  69. ### Cross-Machine Setup
  70. #### 1. Configure Hub & Generate a Pairing Code
  71. 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.
  72. With the Hub stopped, initialize and generate a pairing code:
  73. ```powershell
  74. node hub/src/cli.mjs --config hub/hub.json init
  75. node hub/src/cli.mjs --config hub/hub.json pair-create --name game-pc --ttl-sec 600
  76. ```
  77. #### 2. Register the MCP Server in Your AI Host
  78. Example Codex configuration (`stdout` is reserved for MCP; logs go to `stderr`):
  79. ```toml
  80. [mcp_servers.yonder]
  81. command = "C:/Program Files/nodejs/node.exe"
  82. args = [
  83. "<path-to-yonder>/hub/src/server.mjs",
  84. "--config",
  85. "<path-to-yonder>/hub/hub.json"
  86. ]
  87. cwd = "<path-to-yonder>"
  88. startup_timeout_sec = 15
  89. tool_timeout_sec = 30
  90. default_tools_approval_mode = "prompt"
  91. enabled_tools = [
  92. "list_machines",
  93. "system_info",
  94. "list_dir",
  95. "read_text",
  96. "run_powershell",
  97. "get_command",
  98. "cancel_command"
  99. ]
  100. [mcp_servers.yonder.tools.run_powershell]
  101. approval_mode = "prompt"
  102. [mcp_servers.yonder.tools.cancel_command]
  103. approval_mode = "prompt"
  104. ```
  105. #### 3. Pair & Run on the Remote Windows PC
  106. Copy `client/client.ps1` to the remote Windows PC (no Node.js needed) and run:
  107. ```powershell
  108. # 1) Pair (enter the pairing code when prompted)
  109. # Use -ExecutionMode trusted_powershell to allow command execution, or read_only for file/system inspection only
  110. 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"
  111. # 2) Start polling for tasks
  112. powershell.exe -NoProfile -File .\client\client.ps1 -Mode Run -Config .\client.json
  113. ```
  114. The client stores its token via Windows DPAPI at `%LOCALAPPDATA%\RemotePcClient\<hubId>\<machineId>\credential.dat`. `client.json` does not contain plaintext tokens.
  115. #### 4. Revoke a Machine
  116. Stop the Hub and run:
  117. ```powershell
  118. node hub/src/cli.mjs --config hub/hub.json revoke --machine game-pc
  119. ```
  120. ---
  121. ## Project Structure
  122. ```text
  123. yonder/
  124. ├── .agents/skills/remote-pc/ # Skill instructions for AI hosts
  125. ├── client/ # Windows PowerShell 5.1 client & example config
  126. ├── docs/ # Installation, acceptance, and troubleshooting guides
  127. ├── hub/ # Node.js MCP Hub server & local admin CLI
  128. ├── samples/ # Minimal diagnostic sample script
  129. ├── schemas/ # JSON Schemas for config and results
  130. └── tests/ # Protocol and Windows client test suites
  131. ```
  132. ---
  133. ## Tests
  134. Run the test suite from `hub/`:
  135. ```powershell
  136. cd hub
  137. npm test
  138. ```
  139. ---
  140. ## Documentation & License
  141. - [Installation & Pairing Guide (zh-CN)](docs/install.md)
  142. - [Acceptance Checklist (zh-CN)](docs/acceptance.md)
  143. - [Troubleshooting (zh-CN)](docs/troubleshooting.md)
  144. - License: [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.