
yivpn-agent-cli
net.yivpn/yivpn-agent-cli
Dual-mode AI Agent VPN MCP server: smart split-tunneling, rootless proxy & 90m free trial.
Documentation
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.
Environment-Aware Routing & Safety Guardrails (v2.2.1)
- Zero-App Cloud, Docker & Headless Sandbox (
127.0.0.1:10808Only — Zero SSH Drop):- Zero email registration, zero GUI app, zero
rootprivileges, and never touches Linux host routes. - Instant
$090-minute / 1 GiB Free Trial (connect --auto-trial— works directly on domestic ISPs AND behind existing proxies/cloud sandboxes) or multi-regionUS/JP/SG/HKvia Hosted Checkout ($2.99/¥19.90) orx402Base USDC.
- Zero email registration, zero GUI app, zero
- 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, no1 GiBcap, and zero WinINET registry conflicts. - Detects active third-party proxies (
Karing,Clash,Mihomo,v2rayNviaosSystemProxy.portListening+ownerProcess) and refuses to clobber their OS system proxy unless--force-system-proxyis passed. - When
--system-proxyis applied, spawns anautoRestoreWatchdogthat automatically restores previous OS proxy settings ondisconnect, ifsing-boxexits, or when the 90-minute trial expires (browsers never hang on a dead port).
- Detects installed YIVPN Desktop (
- Mainland China Zero-Proxy Bootstrap (GFW-Safe First-Party Mirror):
- Download
bin/yivpn-agent.mjsdirectly fromhttps://yivpn.net/vpn-api/yivpn-agent.mjsinto~/.yivpn-agent/yivpn-agent.mjs(SHA-256:6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63, checksum endpoint:https://yivpn.net/vpn-api/yivpn-agent.mjs.sha256).
- Download
- Unified Human Docs:
https://yivpn.net/en/vpn-api/(简体中文) - Unified Agent Quickstart (
llms.txt v2.2):https://yivpn.net/vpn-api/llms.txt - First-Party CLI Mirror (No-Proxy China Safe):
https://yivpn.net/vpn-api/yivpn-agent.mjs - OpenAPI 3.1 Specification:
https://yivpn.net/vpn-api/openapi.yaml - Live Discovery API:
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:
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)
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
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 keyX-YIVPN-Timestamp: Unix epoch seconds (10digits, within±300s)X-YIVPN-Signature: Base64 (or 128-char hex) 64-byte Ed25519 signature over UTF-8:
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 (zero-dependency Node.js, SHA-256 6dc9cab1175e626726c56eb63e4af15473aee8eefb6c396f53a8b7930badef63) and python/sign_request.py (Python 3) for reference implementations.
License
MIT © YIVPN
https://github.com/yivpn-official/yivpn-agent-cli/releases/download/v2.2.2/yivpn-agent-cli-v2.2.2.mcpb# mcpb: https://github.com/yivpn-official/yivpn-agent-cli/releases/download/v2.2.2/yivpn-agent-cli-v2.2.2.mcpb