Skip to content
Back to search

yivpn-agent-vpn

SkillWorks with Claude CodeGitHub

Unified YIVPN AI Agent network tool (v2.2.1). Automatically bridges to a local YIVPN Desktop App MCP server (Windows/macOS live split-tunneling & rollback) OR runs a zero-account, rootless 127.0.0.1:10808 sing-box 1.12+/1.14+ VPN proxy daemon in cloud VMs, Docker containers, and personal workstations ($0 90m/1GiB Trial + Checkout/x402 + conflict-safe OS system proxy with automatic expiry restore watchdog).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yivpn-official--yivpn-agent-cli/badge.svg)](/listings/yivpn-official--yivpn-agent-cli)

HTML

<a href="/listings/yivpn-official--yivpn-agent-cli"><img src="/api/listings/yivpn-official--yivpn-agent-cli/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.

A. Recommended Persistent Single-File Setup (Mainland China & Global Safe)

mkdir -p ~/.yivpn-agent
curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs

# Pre-check installed Desktop App & any active external proxy:
node ~/.yivpn-agent/yivpn-agent.mjs status

# Linux / Cloud VM / Terminal-only proxy (127.0.0.1:10808, SSH-safe):
node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial

# Personal Windows / macOS PC (conflict-safe browser system proxy + expiry auto-restore watchdog):
node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial --system-proxy

# Verify direct ISP vs tunnel exit (--noproxy "*" bypasses existing env proxies):
curl -fsSL --noproxy "*" https://cloudflare.com/cdn-cgi/trace
curl -fsSL -x http://127.0.0.1:10808 https://cloudflare.com/cdn-cgi/trace

# Stop daemon & restore OS system proxy cleanly:
node ~/.yivpn-agent/yivpn-agent.mjs disconnect

B. Unified MCP Server Registration (`stdio`)

# Register MCP (Zero-App Cloud / Docker / Sandbox — exposes 11 tools)
claude mcp add yivpn -- node ~/.yivpn-agent/yivpn-agent.mjs mcp

# Register MCP (YIVPN Desktop App v1.0.6+ Local Split-Tunneling Bridge — exposes 8 live kernel tools)
claude mcp add yivpn -e YIVPN_MCP_TOKEN=yivpn_mcp_<YOUR_TOKEN> -- node ~/.yivpn-agent/yivpn-agent.mjs mcp

# Paid Multi-Region Plan ($2.99 / ¥19.90 1mo — unlocks US/JP/SG/HK across 5 concurrent devices)
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

# Fast large file download once 127.0.0.1:10808 is active:
curl -fL --proxy http://127.0.0.1:10808 https://yivpn.net/downloads/YIVPN_1.0.6_x64.msi -o YIVPN_1.0.6_x64.msi

---

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.

SKILL.md · Manifest · 43 lines
  1. ---
  2. name: yivpn-agent-vpn
  3. description: Unified YIVPN AI Agent network tool (v2.2.1). Automatically bridges to a local YIVPN Desktop App MCP server (Windows/macOS live split-tunneling & rollback) OR runs a zero-account, rootless 127.0.0.1:10808 sing-box 1.12+/1.14+ VPN proxy daemon in cloud VMs, Docker containers, and personal workstations ($0 90m/1GiB Trial + Checkout/x402 + conflict-safe OS system proxy with automatic expiry restore watchdog).
  4. ---
  5. # YIVPN Unified AI Agent MCP & VPN Skill (`v2.2.1`)
  6. ## Step 1: Persistent First-Party Bootstrap & Pre-Check (`status`)
  7. Save the zero-dependency CLI to `~/.yivpn-agent/yivpn-agent.mjs` (never volatile `%TEMP%`, and avoid `npx github:...` before connecting in Mainland China) and inspect host state first:
  8. ```bash
  9. mkdir -p ~/.yivpn-agent
  10. curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs
  11. node ~/.yivpn-agent/yivpn-agent.mjs status
  12. ```
  13. ## Step 2: Environment & Proxy Conflict Decision Tree
  14. 1. **Personal Windows / macOS Computer with `desktop_app.installed == true`**
  15. - **YIVPN Desktop (`v1.0.6+`)** already includes **90 min/day of `$0` free global OS TUN** with zero login, no `1 GiB` cap, and zero WinINET system-proxy conflicts!
  16. - Prefer launching Desktop GUI (`node ~/.yivpn-agent/yivpn-agent.mjs launch-desktop`) or connect to its Local MCP (`YIVPN_MCP_TOKEN=yivpn_mcp_...`) for YiPro split-tunneling.
  17. 2. **Existing Third-Party Proxy Active (`local_proxy.osSystemProxy.externalConflict == true`)**
  18. - When `status` shows `portListening: true` on another port (e.g. `karingService.exe` on `3067` or `verge-mihomo` on `7890`), **DO NOT overwrite OS system proxy** (background daemons will fight over WinINET/`networksetup`).
  19. - Run `node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial` (local `127.0.0.1:10808` only) and ask the user to toggle off System Proxy inside their existing client first if they want all browser traffic switched to YIVPN.
  20. 3. **Personal Windows / macOS Computer without Desktop App or Conflicting Proxy**
  21. - Run `node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial --system-proxy`.
  22. - Built-in `autoRestoreWatchdog` automatically restores OS proxy settings on `disconnect`, if `sing-box` exits, or when the 90-minute trial expires.
  23. 4. **Linux Cloud VM / SSH Host / Docker / Headless Sandbox**
  24. - **NEVER** pass `--system-proxy` or modify host routes. Start only `127.0.0.1:10808` (`connect --auto-trial`) and pass `HTTPS_PROXY=http://127.0.0.1:10808`.
  25. ## Step 3: Verification & PowerShell Guardrails
  26. - **Accurate Direct vs Tunnel Probe**: Always pass `--noproxy "*"` when testing direct ISP connectivity (`curl -fsSL --noproxy "*" https://cloudflare.com/cdn-cgi/trace`) vs tunnel (`curl -fsSL -x http://127.0.0.1:10808 https://cloudflare.com/cdn-cgi/trace`).
  27. - **Fast Large Downloads via Tunnel**: Once `127.0.0.1:10808` is up, pass `-x http://127.0.0.1:10808` when downloading installers (`https://yivpn.net/downloads/*`) or GitHub releases.
  28. - **Windows PowerShell Rules**: Invoke `curl.exe` (not PowerShell's `curl` alias) and `node "$HOME\.yivpn-agent\yivpn-agent.mjs"`. Do NOT edit `~/.yivpn-agent/*.json` with PowerShell 5.1 `Set-Content -Encoding utf8`.
  29. ## References
  30. - Unified Agent Quickstart (`llms.txt v2.2`): `https://yivpn.net/vpn-api/llms.txt`
  31. - First-Party Single-File CLI Mirror (SHA-256 `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63`): `https://yivpn.net/vpn-api/yivpn-agent.mjs`
  32. - OpenAPI 3.1 Specification: `https://yivpn.net/vpn-api/openapi.yaml`
  33. - Live Discovery Endpoint: `https://yivpn.net/api/v1/vpn`
README.md · README · 100 lines
  1. # yivpn-agent-cli (v2.2.1 — Unified AI Agent MCP Server, Proxy Daemon & VPN API CLI)
  2. Official zero-dependency **Model Context Protocol (MCP)** server, built-in **rootless `sing-box 1.12+ / 1.14+` proxy daemon**, **conflict-safe Windows/macOS system proxy manager with automatic trial-expiry restore watchdog**, Node.js CLI, Python `ed25519-v1` reference signer, and AI Agent `SKILL.md` for **[YIVPN AI Agent & Developer Hub](https://yivpn.net/en/vpn-api/)**.
  3. ### Environment-Aware Routing & Safety Guardrails (`v2.2.1`)
  4. 1. **Zero-App Cloud, Docker & Headless Sandbox (`127.0.0.1:10808` Only — Zero SSH Drop)**:
  5. - Zero email registration, zero GUI app, zero `root` privileges, and **never touches Linux host routes**.
  6. - Instant **`$0` 90-minute / 1 GiB Free Trial** (`connect --auto-trial` — works directly on domestic ISPs AND behind existing proxies/cloud sandboxes) or multi-region `US/JP/SG/HK` via Hosted Checkout (`$2.99` / `¥19.90`) or `x402` Base USDC.
  7. 2. **Personal Windows / macOS Workstation (Desktop GUI Priority + Conflict-Safe `--system-proxy`)**:
  8. - Detects installed **YIVPN Desktop (`v1.0.6+`)** (`status` → `desktop_app.installed` / `launch-desktop`), which provides **90 min/day free global OS TUN** with zero login, no `1 GiB` cap, and zero WinINET registry conflicts.
  9. - Detects active third-party proxies (`Karing`, `Clash`, `Mihomo`, `v2rayN` via `osSystemProxy.portListening` + `ownerProcess`) and refuses to clobber their OS system proxy unless `--force-system-proxy` is passed.
  10. - When `--system-proxy` is applied, spawns an **`autoRestoreWatchdog`** that automatically restores previous OS proxy settings on `disconnect`, if `sing-box` exits, or when the 90-minute trial expires (browsers never hang on a dead port).
  11. 3. **Mainland China Zero-Proxy Bootstrap (GFW-Safe First-Party Mirror)**:
  12. - Download `bin/yivpn-agent.mjs` directly from `https://yivpn.net/vpn-api/yivpn-agent.mjs` into `~/.yivpn-agent/yivpn-agent.mjs` (SHA-256: `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63`, checksum endpoint: `https://yivpn.net/vpn-api/yivpn-agent.mjs.sha256`).
  13. - **Unified Human Docs**: [`https://yivpn.net/en/vpn-api/`](https://yivpn.net/en/vpn-api/) ([简体中文](https://yivpn.net/vpn-api/))
  14. - **Unified Agent Quickstart (`llms.txt v2.2`)**: [`https://yivpn.net/vpn-api/llms.txt`](https://yivpn.net/vpn-api/llms.txt)
  15. - **First-Party CLI Mirror (No-Proxy China Safe)**: [`https://yivpn.net/vpn-api/yivpn-agent.mjs`](https://yivpn.net/vpn-api/yivpn-agent.mjs)
  16. - **OpenAPI 3.1 Specification**: [`https://yivpn.net/vpn-api/openapi.yaml`](https://yivpn.net/vpn-api/openapi.yaml)
  17. - **Live Discovery API**: [`https://yivpn.net/api/v1/vpn`](https://yivpn.net/api/v1/vpn)
  18. ---
  19. ## One-Line Prompt for Your AI Agent
  20. Copy & paste into **Claude Code**, **OpenAI Codex**, **Cursor**, **Doubao**, **Windsurf**, or **OpenClaw**:
  21. ```text
  22. Read the latest guide at https://yivpn.net/vpn-api/llms.txt and auto-connect this environment to YIVPN (claim the free 90-min trial if needed).
  23. ```
  24. ---
  25. ## Quickstart Commands (Node.js 20+)
  26. ### A. Recommended Persistent Single-File Setup (Mainland China & Global Safe)
  27. ```bash
  28. mkdir -p ~/.yivpn-agent
  29. curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o ~/.yivpn-agent/yivpn-agent.mjs
  30. # Pre-check installed Desktop App & any active external proxy:
  31. node ~/.yivpn-agent/yivpn-agent.mjs status
  32. # Linux / Cloud VM / Terminal-only proxy (127.0.0.1:10808, SSH-safe):
  33. node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial
  34. # Personal Windows / macOS PC (conflict-safe browser system proxy + expiry auto-restore watchdog):
  35. node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial --system-proxy
  36. # Verify direct ISP vs tunnel exit (--noproxy "*" bypasses existing env proxies):
  37. curl -fsSL --noproxy "*" https://cloudflare.com/cdn-cgi/trace
  38. curl -fsSL -x http://127.0.0.1:10808 https://cloudflare.com/cdn-cgi/trace
  39. # Stop daemon & restore OS system proxy cleanly:
  40. node ~/.yivpn-agent/yivpn-agent.mjs disconnect
  41. ```
  42. ### B. Unified MCP Server Registration (`stdio`)
  43. ```bash
  44. # Register MCP (Zero-App Cloud / Docker / Sandbox — exposes 11 tools)
  45. claude mcp add yivpn -- node ~/.yivpn-agent/yivpn-agent.mjs mcp
  46. # Register MCP (YIVPN Desktop App v1.0.6+ Local Split-Tunneling Bridge — exposes 8 live kernel tools)
  47. claude mcp add yivpn -e YIVPN_MCP_TOKEN=yivpn_mcp_<YOUR_TOKEN> -- node ~/.yivpn-agent/yivpn-agent.mjs mcp
  48. # Paid Multi-Region Plan ($2.99 / ¥19.90 1mo — unlocks US/JP/SG/HK across 5 concurrent devices)
  49. node ~/.yivpn-agent/yivpn-agent.mjs buy --months 1 --rail checkout
  50. node ~/.yivpn-agent/yivpn-agent.mjs status --wait
  51. node ~/.yivpn-agent/yivpn-agent.mjs connect --region JP
  52. # Fast large file download once 127.0.0.1:10808 is active:
  53. curl -fL --proxy http://127.0.0.1:10808 https://yivpn.net/downloads/YIVPN_1.0.6_x64.msi -o YIVPN_1.0.6_x64.msi
  54. ```
  55. ---
  56. ## Direct REST API & `ed25519-v1` Signing Specification
  57. Every authenticated API request (including `rail: "trial"`) includes three headers:
  58. - `X-YIVPN-Pubkey`: 64-character hex (or Base64) raw 32-byte Ed25519 public key
  59. - `X-YIVPN-Timestamp`: Unix epoch seconds (`10` digits, within `±300s`)
  60. - `X-YIVPN-Signature`: Base64 (or 128-char hex) 64-byte Ed25519 signature over UTF-8:
  61. ```text
  62. yivpn-ed25519-v1
  63. <HTTP_METHOD_UPPERCASE>
  64. <CANONICAL_PATH_INCLUDING_QUERY>
  65. <UNIX_TIMESTAMP_SECONDS>
  66. <LOWERCASE_SHA256_HEX_OF_RAW_REQUEST_BODY>
  67. ```
  68. See [`bin/yivpn-agent.mjs`](./bin/yivpn-agent.mjs) (zero-dependency Node.js, SHA-256 `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63`) and [`python/sign_request.py`](./python/sign_request.py) (Python 3) for reference implementations.
  69. ---
  70. ## License
  71. [MIT](./LICENSE) © YIVPN

Ratings and comments

Sign in to rate this skill.

Sign in

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