Repository avatar
AI Tools
v2.2.2
active

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)

  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).

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 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:
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

MCPB
https://github.com/yivpn-official/yivpn-agent-cli/releases/download/v2.2.2/yivpn-agent-cli-v2.2.2.mcpb
Install Command
# mcpb: https://github.com/yivpn-official/yivpn-agent-cli/releases/download/v2.2.2/yivpn-agent-cli-v2.2.2.mcpb