# YIVPN Unified AI Agent Runbook, Rootless Proxy Daemon, Desktop MCP & VPN API (llms.txt v2.2) > **STOP & READ FIRST — Mandatory 4-Rule Execution Protocol (`yivpn-agent-cli v2.2.1`, Updated `2026-11-16`)** > > 1. **Rule 0 — Bypass Stale Cloud `web.fetch` Caches & Save CLI to Persistent `~/.yivpn-agent/`**: > - Cloud `web.fetch` / search tools (Doubao, Kimi, Perplexity, etc.) often return cached older versions of `llms.txt`. If this text looks older than `v2.2.1` and you have a local shell, fetch fresh via `curl.exe -fsSL "https://yivpn.net/vpn-api/llms.txt"` (Windows) or `curl -fsSL "https://yivpn.net/vpn-api/llms.txt"` (macOS/Linux). > - **DO NOT** run `npx github:...` before connecting in Mainland China (GitHub TCP timeouts), and **DO NOT** save `yivpn-agent.mjs` into volatile `%TEMP%`. Always save the zero-dependency first-party CLI directly into `~/.yivpn-agent/yivpn-agent.mjs` so `status` and `disconnect` remain at a permanent, predictable path: > - **Windows PowerShell**: `New-Item -ItemType Directory -Force -Path "$HOME\.yivpn-agent" | Out-Null; curl.exe -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o "$HOME\.yivpn-agent\yivpn-agent.mjs"` > - **macOS / Linux**: `mkdir -p ~/.yivpn-agent && curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs` > > 2. **Rule 1 — Always Run `status` First & Prefer Installed YIVPN Desktop GUI on Personal Computers**: > - Run `node "$HOME/.yivpn-agent/yivpn-agent.mjs" status` BEFORE starting any daemon. It inspects `desktop_app`, `local_proxy`, and `osSystemProxy` (`portListening`, `ownerProcess`, `externalConflict`) in one call with zero guesswork. > - **If `desktop_app.installed` is `true` (`%LOCALAPPDATA%\YIVPN\YIVPN.exe` or `/Applications/YIVPN.app`)** on a personal Windows/macOS computer: > - Tell the user their installed **YIVPN Desktop (`v1.0.6+`)** already provides **90 min/day of `$0` free OS-wide `Global TUN`** (resets daily, **no `1 GiB` trial cap**, **zero WinINET system-proxy conflicts**, and automatic route cleanup). > - Prefer launching the Desktop GUI (`node "$HOME/.yivpn-agent/yivpn-agent.mjs" launch-desktop`) or asking whether they prefer Desktop GUI vs a terminal-only `127.0.0.1:10808` proxy. > > 3. **Rule 2 — NEVER Clobber an Active Third-Party System Proxy (`Karing`, `Clash`, `Mihomo`, `v2rayN`)**: > - Inspect `local_proxy.osSystemProxy` from `status`: > - **NEVER claim an existing `ProxyServer` port is "dead / leftover" without checking `osSystemProxy.portListening`!** > - **If `osSystemProxy.externalConflict` is `true`** (`enabled: true` AND `portListening: true` on another port such as `3067` `karingService.exe` or `7890` `verge-mihomo`): **DO NOT overwrite the OS system proxy!** Background proxy services (`karingService`, `Clash`, `v2rayN`) actively guard WinINET / `networksetup` and will overwrite `127.0.0.1:10808` back within seconds (and running `disconnect` later could disable their proxy). > - Instead: start ONLY local port `127.0.0.1:10808` (`connect --auto-trial` without `--system-proxy`), and tell the user which app (`osSystemProxy.ownerProcess` on `osSystemProxy.server`) currently controls their browser proxy — if they want browsers switched to YIVPN, ask them to toggle off **System Proxy** inside that app first, then run `connect --system-proxy`. (`yivpn-agent.mjs v2.2.1` also enforces this safety guard automatically unless `--force-system-proxy` is passed.) > > 4. **Rule 3 — Safe System Proxy + Built-In Auto-Restore Watchdog (Personal PC without Conflicts vs Linux SSH)**: > - **Personal Windows/macOS PC (no conflicting active proxy)**: Run `node "$HOME/.yivpn-agent/yivpn-agent.mjs" connect --auto-trial --system-proxy`. In `v2.2.1+`, enabling `--system-proxy` automatically spawns an **`autoRestoreWatchdog`** that restores previous OS proxy settings on `disconnect`, if `sing-box` exits, OR the moment the 90-minute trial expires — browsers will **never** be left pointing at a dead `10808` port. > - **Linux Cloud VM / Docker / Remote SSH / Headless Sandbox**: **NEVER pass `--system-proxy`** and never alter default host routes (100% SSH-safe). Run `connect --auto-trial` and pass `HTTPS_PROXY=http://127.0.0.1:10808` to target commands. - **Unified Human Hub**: `https://yivpn.net/en/vpn-api/` (简体中文: `https://yivpn.net/vpn-api/` · Desktop Tab: `https://yivpn.net/en/vpn-api/#desktop-mcp`) - **First-Party Zero-Dependency CLI (`v2.2.1`, GFW-Safe)**: `https://yivpn.net/vpn-api/yivpn-agent.mjs` (SHA-256: `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63` · `.sha256`: `https://yivpn.net/vpn-api/yivpn-agent.mjs.sha256`) - **Cross-Channel Open-Source Repo (`v2.2.1`, identical `bin/yivpn-agent.mjs`)**: `https://github.com/yivpn-official/yivpn-agent-cli` - **Cloud REST API Base**: `https://yivpn.net/api/v1/vpn` · **OpenAPI 3.1 Spec**: `https://yivpn.net/vpn-api/openapi.yaml` --- ## 1. Copy-Paste Quickstart Workflows (Node.js 20+, Zero Account, `$0` 90-Min / 1 GiB Trial) ### 1A. Personal Windows PC (PowerShell — Pre-Check + Conflict-Safe Connect + Accurate Verify) ```powershell # 1. Save zero-dependency CLI to permanent ~/.yivpn-agent/ directory (use curl.exe, NOT PowerShell's curl alias) New-Item -ItemType Directory -Force -Path "$HOME\.yivpn-agent" | Out-Null curl.exe -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o "$HOME\.yivpn-agent\yivpn-agent.mjs" # 2. Inspect installed YIVPN Desktop App & any active external proxy (Karing / Clash / v2rayN) node "$HOME\.yivpn-agent\yivpn-agent.mjs" status # 3a. If YIVPN Desktop GUI is installed and user wants full-PC VPN (90m/day free TUN, no 1 GiB cap): # node "$HOME\.yivpn-agent\yivpn-agent.mjs" launch-desktop # 3b. Otherwise, start 127.0.0.1:10808 + Windows system proxy (auto-skips if externalConflict=true; auto-restores on expiry/disconnect): node "$HOME\.yivpn-agent\yivpn-agent.mjs" connect --auto-trial --system-proxy # 4. Verify true direct ISP vs encrypted tunnel exit (MUST pass --noproxy "*" for direct probe; use cloudflare trace in Mainland China) curl.exe -fsSL --noproxy "*" --max-time 8 https://cloudflare.com/cdn-cgi/trace curl.exe -fsSL -x http://127.0.0.1:10808 --max-time 10 https://cloudflare.com/cdn-cgi/trace # 5. Stop tunnel & restore previous Windows system proxy settings cleanly node "$HOME\.yivpn-agent\yivpn-agent.mjs" disconnect ``` ### 1B. Personal macOS Workstation (Terminal — Pre-Check + Safari / Chrome System Proxy) ```bash mkdir -p ~/.yivpn-agent curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs node ~/.yivpn-agent/yivpn-agent.mjs status # Start tunnel + macOS system proxy (auto-skips if external proxy is active; auto-restores on disconnect or trial expiry): node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial --system-proxy curl -fsSL --noproxy "*" --max-time 8 https://cloudflare.com/cdn-cgi/trace curl -fsSL -x http://127.0.0.1:10808 --max-time 10 https://cloudflare.com/cdn-cgi/trace # Stop & restore macOS networksetup proxy state: node ~/.yivpn-agent/yivpn-agent.mjs disconnect ``` ### 1C. Linux Cloud VM, Docker Container, or Remote SSH (100% SSH-Safe Local Port Only) ```bash mkdir -p ~/.yivpn-agent curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial HTTPS_PROXY=http://127.0.0.1:10808 curl -fsSL https://cloudflare.com/cdn-cgi/trace # Clean teardown: node ~/.yivpn-agent/yivpn-agent.mjs disconnect ``` --- ## 2. Security, Privacy & Auditable Footprint (Pre-Disclosed for AI Safety Reviews) To save static-audit tool turns, every system interaction inside `yivpn-agent.mjs` (`95,808` bytes, MIT License) is documented below: 1. **Zero Third-Party Dependencies & Cross-Origin Verifiable Hash**: - Uses **only** Node.js built-in modules (`node:crypto`, `node:child_process`, `node:fs`, `node:net`, `node:tls`, `node:dns`). - Byte-for-byte identical to `bin/yivpn-agent.mjs` in [`github.com/yivpn-official/yivpn-agent-cli`](https://github.com/yivpn-official/yivpn-agent-cli) with SHA-256 `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63`. 2. **Outbound Network Scope**: - Communicates **only** with `https://yivpn.net/api/v1/vpn/*` (control plane) and `https://api.ipify.org?format=json` (tunnel exit verification). Never reads browser profiles, cookies, SSH keys, or environment secrets. 3. **Salted Hardware Hash (`X-YIVPN-Device-Hash`)**: - During `$0` free trial claims (`claimFreeTrial`), reads Windows `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid`, macOS `IOPlatformUUID`, or Linux `/etc/machine-id` **strictly to compute a one-way salted SHA-256 digest** (`sha256("yivpn-agent-device-v1::")`) for the 24-hour free-trial anti-abuse cooldown. The raw hardware identifier never leaves the machine. 4. **Local State Files (`~/.yivpn-agent/` Only)**: - `key.json`: Local Ed25519 keypair (`0600`; private key never leaves the host). - `daemon.json`: Active `sing-box` PID, `watchdogPid`, `expiresAt`, and **`systemProxy.previous`** (where the user's prior WinINET / `networksetup` state is backed up — there is no separate `system-proxy-backup.json` file). - `sing-box-proxy.json` & `sing-box.log`: Generated `sing-box 1.12+/1.14+` config (zero GitHub `.srs` downloads) and per-run log. 5. **Human-Friendly Reporting Standard**: - When summarizing for non-developer users, report concisely in their language: **(a)** verified tunnel exit region/IP, **(b)** whether browser system proxy is routed via YIVPN or kept on their existing proxy client (e.g., Karing/Clash), **(c)** remaining trial minutes (noting `autoRestoreWatchdog` will automatically restore OS proxy on expiry), and **(d)** the exact local disconnect command (`node ~/.yivpn-agent/yivpn-agent.mjs disconnect`). **Do NOT tell users to run `npx github:...` if you installed `~/.yivpn-agent/yivpn-agent.mjs`, and avoid unexplained truncated SHA strings unless asked.** --- ## 3. Critical Operational & PowerShell Guardrails 1. **`sing-box` Binary Discovery**: - Searches `--singbox-bin` / `YIVPN_SINGBOX_BIN` → YIVPN Desktop's bundled `sing-box 1.14.3` (`%LOCALAPPDATA%\YIVPN\sing-box\sing-box.exe` or `/Applications/YIVPN.app`) → `~/.yivpn-agent/bin/` → `PATH` (`sing-box >= 1.12`). - If no `sing-box` binary exists and `github.com` is blocked, download **YIVPN Desktop (`v1.0.6`)** from first-party CDN (`https://yivpn.net/downloads/YIVPN_1.0.6_x64.msi` or `https://yivpn.net/downloads/YIVPN_1.0.6_universal.dmg`). 2. **Accurate Direct-vs-Tunnel Testing**: - Always pass `--noproxy "*"` when probing the user's direct ISP connection (`curl.exe -fsSL --noproxy "*" https://cloudflare.com/cdn-cgi/trace`); without `--noproxy "*"`, `curl` may follow existing proxy env vars and misreport an existing VPN exit as the user's "direct" IP. - Prefer `https://cloudflare.com/cdn-cgi/trace` over `api.ipify.org` for direct probes in Mainland China (`api.ipify.org` frequently times out on direct mobile/broadband carriers). 3. **Accelerate Large Downloads Once Connected**: - Once `127.0.0.1:10808` is active, pass `-x http://127.0.0.1:10808` to `curl.exe` / `curl` when downloading `.msi`, `.dmg`, `.apk`, or GitHub releases. 4. **Windows PowerShell Rules**: - Always call `curl.exe` (not PowerShell's `curl` alias) and `node "$HOME\.yivpn-agent\yivpn-agent.mjs"` (avoids `npx.ps1` `ExecutionPolicy` blocks). - Never rewrite `~/.yivpn-agent/*.json` with PowerShell 5.1 `Set-Content -Encoding UTF8` (injects UTF-8 BOM). - Valid CLI subcommands (`v2.2.1`): `mcp`, `connect` (`--auto-trial`, `--system-proxy`, `--force-system-proxy`, `--region auto|US|JP|SG|HK`, `--port 10808`, `--singbox-bin `), `disconnect`, `launch-desktop`, `status` (`--wait`), `trial`, `buy` (`--months 1|3|6|12 --rail checkout|x402`), `locations`, `settings` (`--guardrails malware,ads,adult,smart_split|none`), `config`, `rotate`, `revoke`, `discover`, `keygen`, `version` (`-v`), `selftest`. --- ## 4. Unified MCP Registration (`stdio` — Zero-App Mode A & Desktop Bridge Mode B) Register once in Claude Code, OpenAI Codex, Cursor, Windsurf, Doubao, or OpenClaw using the persistent local file: ```bash # Mode A — Zero-App Cloud, Sandbox & Personal Proxy (11 tools, GFW & Windows ExecutionPolicy safe): claude mcp add yivpn -- node ~/.yivpn-agent/yivpn-agent.mjs mcp # Mode B — Desktop Workstation Bridge (8 live sing-box split-tunnel tools when YIVPN_MCP_TOKEN is set): claude mcp add yivpn -e YIVPN_MCP_TOKEN=yivpn_mcp_ -- node ~/.yivpn-agent/yivpn-agent.mjs mcp ``` *(Outside restricted networks, `npx --yes github:yivpn-official/yivpn-agent-cli mcp` is also supported.)* ### Mode A: Zero-App Cloud, Sandbox & Personal Proxy (`11` MCP Tools, Default without `YIVPN_MCP_TOKEN`) | Tool | Purpose | | :--- | :--- | | `get_capabilities` | Reports runtime mode, detected `sing-box` binary, installed/running YIVPN Desktop App, active OS system proxy owner, and cloud discovery. | | `get_vpn_status` | Returns live local proxy daemon state (`connected`, `pid`, `autoRestoreWatchdog`, `osSystemProxy`), `desktopAppInstalled`, AND cloud entitlement status. | | `list_servers` | Lists authorized `Hysteria2` & `VLESS` exit nodes (`US-Ohio` on trial; `US`, `JP`, `SG`, `HK` on paid plans). | | `connect_vpn` | **One-call tunnel start**: `autoClaimTrial: true` claims `$0` 90m/1GiB trial if needed, spawns `sing-box` on `127.0.0.1:10808`, safely applies OS proxy (`systemProxy: true`, skipping active conflicting proxies unless `forceSystemProxy: true`), starts expiry auto-restore watchdog, and verifies exit IP. | | `disconnect_vpn` | Stops the managed `sing-box` daemon & watchdog, restores OS system proxy if enabled by YIVPN, and verifies port release. | | `diagnose_connection` | Resolves DNS `A`/`AAAA` and runs side-by-side `directProbe` + `tunnelProbe` (via `127.0.0.1:10808` HTTP `CONNECT`). | | `claim_free_trial` | Mints `~/.yivpn-agent/key.json` if missing and signs `rail: "trial"` (`$0` 90m / `1 GiB`, 24h cooldown). | | `purchase_vpn_entitlement` | Initiates zero-account Hosted Checkout (`$2.99` / `¥19.90` 1mo) or `x402` Base USDC (`months`: `1\|3\|6\|12`). | | `configure_vpn_guardrails` | Reads/updates tunnel DNS `guardrails` (`malware`, `ads`, `adult`, `smart_split`) and `preferredRegion`. | | `export_singbox_config` | Exports raw `sing-box 1.12+/1.14+` JSON (`mode=proxy\|tun`) for custom orchestration. | | `rotate_or_revoke_key` | Atomically transfers remaining time to a fresh Ed25519 keypair (`rotate`) or revokes (`revoke`). | ### Mode B: Desktop Workstation Local MCP (`YIVPN v1.0.6+` YiPro Split-Tunnel Kernel Control) - **Important distinction**: Standard users on YIVPN Desktop (`v1.0.6+`) ALREADY get **90 min/day of `$0` free OS-wide TUN** directly inside the GUI app with zero login or `YIVPN_MCP_TOKEN`. Mode B (`YIVPN_MCP_TOKEN`) is for **YiPro** users who want an AI Agent to inspect live kernel routes or edit split-tunneling rules (`Settings → Connection Strategy → Local MCP Service (AI Agent)`). - Exposes `get_capabilities`, `get_vpn_status`, `list_servers`, `connect_vpn`, `disconnect_vpn`, `diagnose_connection`, `preview_routing_rules`, `apply_routing_rules` (optimistic `policyVersion` lock + safety snapshot + live `sing-box.log` verification + automatic rollback), and `rollback_routing_rules`. - Always call `preview_routing_rules` before `apply_routing_rules`; prefer verified `service_preset` IDs (`openai`, `anthropic`, `github`, `google`, `telegram`, `xiaohongshu`, `baidu`, `wechat`, `amap`, `alibaba`, `bilibili`, `qichacha`). `process_name` rules require `tun` mode. --- ## 5. Paid Multi-Region Upgrade & Direct REST API (`ed25519-v1`) Upgrade any Ed25519 key to unlock **`US`, `JP`, `SG`, `HK`** multi-region exits across up to `5` concurrent sandboxes (`$2.99`/1mo, `$6.99`/3mo, `$12.99`/6mo, `$21.99`/12mo USD; `¥19.90`–`¥159.90` CNY via Alipay/WeChat/Card; or autonomous `x402` Base USDC): ```bash node ~/.yivpn-agent/yivpn-agent.mjs buy --months 1 --rail checkout node ~/.yivpn-agent/yivpn-agent.mjs status --wait node ~/.yivpn-agent/yivpn-agent.mjs connect --region JP ``` ### Signing Canonical Payload (`ed25519-v1`) Your **32-byte raw Ed25519 public key** (64-char lowercase hex or base64) is your sole account identity. Protected endpoints (`status`, `locations`, `config`, `settings`, `rotate`, `entitlements` DELETE) and `rail: "trial"` require headers `X-YIVPN-Pubkey`, `X-YIVPN-Timestamp` (10-digit Unix seconds, `±300`s), and `X-YIVPN-Signature` (Base64 Ed25519 signature) over UTF-8: ```text yivpn-ed25519-v1 ``` *(Empty body SHA-256 is `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`.)* | Method | Path | Auth | Description | | :--- | :--- | :--- | :--- | | `GET` | `/api/v1/vpn` | Public | Machine discovery: `free_trial` (with `china_direct_script`), pricing (`1/3/6/12` mo), protocols, regions, guardrails, and payment rails | | `POST` | `/api/v1/vpn/entitlements` | `ed25519-v1` (`trial`) / Public (`checkout`) / `x402` | Claim `$0` 90m/1GiB trial (`rail: "trial"`) or buy multi-region access (`$2.99–$21.99` USD; `¥19.90–¥159.90` CNY; Base USDC `x402`) | | `GET` | `/api/v1/vpn/status` | `ed25519-v1` | Check `active`, `ready`, `expires_at`, `remaining_seconds`, `trial` metadata, and active `settings` | | `GET` | `/api/v1/vpn/locations` | `ed25519-v1` | List provisioned `Hysteria2` & `VLESS` nodes (`US-Ohio` on trial; `US`, `JP`, `SG`, `HK` on paid plans) | | `GET` | `/api/v1/vpn/config` | `ed25519-v1` | Fetch native `sing-box 1.12+/1.14+` JSON (`?mode=proxy\|tun®ion=auto\|US\|JP\|SG\|HK&port=10808&raw=1`, zero GitHub `.srs` dependencies) | | `GET\|PUT` | `/api/v1/vpn/settings` | `ed25519-v1` | Read or update tunnel DNS `guardrails` (`malware`, `ads`, `adult`, `smart_split`) and `preferred_region` | | `POST` | `/api/v1/vpn/rotate` | `ed25519-v1` | Atomically transfer remaining subscription time to `{"new_pubkey":"..."}` | | `DELETE` | `/api/v1/vpn/entitlements` | `ed25519-v1` | Immediately revoke entitlement and disable upstream node credentials |