yivpn-agent-vpn
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.
Badge for your README
Markdown
[](/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
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
- ---
- name: yivpn-agent-vpn
- 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).
- ---
- # YIVPN Unified AI Agent MCP & VPN Skill (`v2.2.1`)
- ## Step 1: Persistent First-Party Bootstrap & Pre-Check (`status`)
- 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:
- ```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
- ```
- ## Step 2: Environment & Proxy Conflict Decision Tree
- 1. **Personal Windows / macOS Computer with `desktop_app.installed == true`**
- - **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!
- - 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.
- 2. **Existing Third-Party Proxy Active (`local_proxy.osSystemProxy.externalConflict == true`)**
- - 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`).
- - 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.
- 3. **Personal Windows / macOS Computer without Desktop App or Conflicting Proxy**
- - Run `node ~/.yivpn-agent/yivpn-agent.mjs connect --auto-trial --system-proxy`.
- - Built-in `autoRestoreWatchdog` automatically restores OS proxy settings on `disconnect`, if `sing-box` exits, or when the 90-minute trial expires.
- 4. **Linux Cloud VM / SSH Host / Docker / Headless Sandbox**
- - **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`.
- ## Step 3: Verification & PowerShell Guardrails
- - **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`).
- - **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.
- - **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`.
- ## References
- - Unified Agent Quickstart (`llms.txt v2.2`): `https://yivpn.net/vpn-api/llms.txt`
- - First-Party Single-File CLI Mirror (SHA-256 `6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63`): `https://yivpn.net/vpn-api/yivpn-agent.mjs`
- - OpenAPI 3.1 Specification: `https://yivpn.net/vpn-api/openapi.yaml`
- - Live Discovery Endpoint: `https://yivpn.net/api/v1/vpn`
README.md · README · 100 lines
- # yivpn-agent-cli (v2.2.1 — Unified AI Agent MCP Server, Proxy Daemon & VPN API CLI)
- 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/)**.
- ### Environment-Aware Routing & Safety Guardrails (`v2.2.1`)
- 1. **Zero-App Cloud, Docker & Headless Sandbox (`127.0.0.1:10808` Only — Zero SSH Drop)**:
- - Zero email registration, zero GUI app, zero `root` privileges, and **never touches Linux host routes**.
- - 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.
- 2. **Personal Windows / macOS Workstation (Desktop GUI Priority + Conflict-Safe `--system-proxy`)**:
- - 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.
- - 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.
- - 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).
- 3. **Mainland China Zero-Proxy Bootstrap (GFW-Safe First-Party Mirror)**:
- - 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`).
- - **Unified Human Docs**: [`https://yivpn.net/en/vpn-api/`](https://yivpn.net/en/vpn-api/) ([简体中文](https://yivpn.net/vpn-api/))
- - **Unified Agent Quickstart (`llms.txt v2.2`)**: [`https://yivpn.net/vpn-api/llms.txt`](https://yivpn.net/vpn-api/llms.txt)
- - **First-Party CLI Mirror (No-Proxy China Safe)**: [`https://yivpn.net/vpn-api/yivpn-agent.mjs`](https://yivpn.net/vpn-api/yivpn-agent.mjs)
- - **OpenAPI 3.1 Specification**: [`https://yivpn.net/vpn-api/openapi.yaml`](https://yivpn.net/vpn-api/openapi.yaml)
- - **Live Discovery API**: [`https://yivpn.net/api/v1/vpn`](https://yivpn.net/api/v1/vpn)
- ---
- ## One-Line Prompt for Your AI Agent
- Copy & paste into **Claude Code**, **OpenAI Codex**, **Cursor**, **Doubao**, **Windsurf**, or **OpenClaw**:
- ```text
- 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).
- ```
- ---
- ## Quickstart Commands (Node.js 20+)
- ### A. Recommended Persistent Single-File Setup (Mainland China & Global Safe)
- ```bash
- 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`)
- ```bash
- # 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
- ```
- ---
- ## Direct REST API & `ed25519-v1` Signing Specification
- Every authenticated API request (including `rail: "trial"`) includes three headers:
- - `X-YIVPN-Pubkey`: 64-character hex (or Base64) raw 32-byte Ed25519 public key
- - `X-YIVPN-Timestamp`: Unix epoch seconds (`10` digits, within `±300s`)
- - `X-YIVPN-Signature`: Base64 (or 128-char hex) 64-byte Ed25519 signature over UTF-8:
- ```text
- yivpn-ed25519-v1
- <HTTP_METHOD_UPPERCASE>
- <CANONICAL_PATH_INCLUDING_QUERY>
- <UNIX_TIMESTAMP_SECONDS>
- <LOWERCASE_SHA256_HEX_OF_RAW_REQUEST_BODY>
- ```
- 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.
- ---
- ## License
- [MIT](./LICENSE) © YIVPN
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.