Guide · Developer & MCP

Proxy & Split-Tunnel Setup for Cursor, Claude Code, Codex & MCP

Step-by-step split-tunnel proxy guide for Cursor, Claude Code, OpenAI Codex, and GitHub Copilot using Layer-3 Global TUN and YIVPN local MCP tools.

Published: Last verified: 8 min read Tested on: Windows 11 / macOS 15 · Cursor / Claude Code / yivpn-agent-cli v2.1

Configuring a network proxy for a web browser takes seconds, yet developers routinely hit ETIMEDOUT, stalled SSE token streams, or broken intranet Git remotes the moment they launch Cursor, Claude Code, OpenAI Codex CLI, or GitHub Copilot. The root cause is architectural: IDE extension hosts, language servers, and CLI subprocesses do not share the browser's proxy stack. This guide walks through three clean, battle-tested setups on Windows, macOS, and headless Linux.

Key Takeaways (TL;DR)

  • CLI coding agents (Claude Code, OpenAI Codex CLI, Git, Cargo, npm) frequently ignore OS desktop proxy settings; Layer-3 Global TUN captures them transparently without per-shell env vars.
  • Smart split-tunneling keeps localhost, Docker bridges, corporate intranet hosts, and domestic package mirrors on direct ISP routing at zero added latency.
  • If Cursor streaming completions stall behind strict firewalls or middleboxes, pairing HTTP/1.1 compatibility mode with smart split routing eliminates mid-stream resets.
  • With YIVPN's open-source MCP server (yivpn-agent-cli), coding agents can inspect tunnel health, preview split-route diffs, and roll back routing rules autonomously.

1. Why AI IDEs and Terminal Agents Ignore OS System Proxies

Traditional proxy utilities default to toggling the operating system's application-layer System Proxy. Modern AI developer workflows, however, spawn heterogeneous child processes across multiple runtimes:

Tool / Runtime LayerDefault Socket BehaviorBehavior Under OS System Proxy OnlyRecommended Routing Method
Cursor / VS Code UIChromium layer reads OS proxyChat works, but background indexing or HTTP/2 streams may stallGlobal TUN or IDE Proxy + HTTP/1.1 fallback
Claude Code (claude CLI)Node.js fetch connects directly to NICImmediate connection timeout on restricted networksGlobal TUN or explicit HTTPS_PROXY
OpenAI Codex / Python SDKshttpx / Rust TLS reads env varsHangs unless shell environment variables are setGlobal TUN or local daemon port
Git over SSH (tcp/22)OpenSSH ignores HTTP proxy settingshttps:// clones succeed while git@github.com failsGlobal TUN or SSH ProxyCommand

2. Method A (Recommended): Zero-Config Layer-3 Global TUN + Smart Split

On Windows 10/11 and macOS 11+, the cleanest way to route every IDE extension host, CLI binary, and Git transport without polluting .zshrc or Docker build environments is Layer-3 Global TUN paired with Smart Split:

  1. Install the official YIVPN Desktop Client v1.0.4, which bundles a self-contained offline sing-box 1.14.3 engine (Wintun on Windows, native utun on macOS).
  2. Enable Global TUN alongside the default Smart Split profile (powered by our open-source singbox-smart-split rule generator).
  3. Connect in one click. The OS kernel routes packets for api.anthropic.com, api.openai.com, cursor.sh, github.com, and huggingface.co through the encrypted Hysteria2 or VLESS+REALITY tunnel while keeping localhost, RFC1918 LAN subnets, and local cloud/banking endpoints on direct ISP routing.
Fixing stalled Cursor streams: If long multi-file Composer or Agent edits freeze mid-response on networks with aggressive middleboxes, open Cursor Settings, search for Cursor › General: Disable Http2, and enable it alongside YIVPN Smart Split.

3. Method B: Scoped Per-Shell Proxy Functions with NO_PROXY Hygiene

When working on a locked-down workstation without administrator privileges for virtual TUN adapters, you can bind a local HTTP/SOCKS5 endpoint (for example via yivpn-agent-cli on 127.0.0.1:10808) and toggle proxy variables per terminal session while explicitly protecting private subnets:

BASH
# Add to ~/.zshrc or ~/.bashrc for clean on-demand CLI proxy toggling
proxy_on() {
  export HTTP_PROXY="http://127.0.0.1:10808"
  export HTTPS_PROXY="http://127.0.0.1:10808"
  export ALL_PROXY="socks5h://127.0.0.1:10809"
  export NO_PROXY="localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.local,.internal"
  echo "AI CLI proxy active on 127.0.0.1:10808 (LAN & localhost bypassed)"
}

proxy_off() {
  unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
  echo "AI CLI proxy disabled"
}

On Windows PowerShell, test connectivity in the current session with:

POWERSHELL
$env:HTTPS_PROXY = "http://127.0.0.1:10808"
$env:NO_PROXY = "localhost,127.0.0.1,192.168.*,10.*"
curl.exe -I https://api.anthropic.com

4. Method C: Autonomous Split-Tunnel Control via YIVPN Local MCP

When debugging workflows that mix external AI/cloud APIs with private staging clusters, switching VPN toggles manually breaks flow. YIVPN provides an open-source Model Context Protocol (MCP) bridge (documented on our AI & API Hub):

JSON
{
  "mcpServers": {
    "yivpn": {
      "command": "npx",
      "args": ["-y", "yivpn-agent-cli@latest", "mcp"]
    }
  }
}

Once registered in Claude Code or Cursor, your coding agent can safely inspect and adjust split-tunnel rules on demand:

  • Run preview_routing_rules before applying changes to verify exact domain/CIDR diffs.
  • Keep internal staging domains on direct routing while routing blocked external APIs or package registries through the tunnel.
  • Run rollback_routing_rules to restore the previous working snapshot in one command if a rule causes unexpected behavior.

5. Rootless Daemon Mode for Headless Linux, WSL2 & Remote Containers

Running autonomous coding agents inside a remote Linux VM, devcontainer, or WSL2 instance without a GUI? Launch the zero-dependency CLI daemon directly using the 90-minute daily free tier—no account or credit card required:

BASH
# Fetch the zero-dependency ESM CLI and start a local rootless proxy daemon
curl -fsSL https://yivpn.net/vpn-api/yivpn-agent.mjs -o yivpn-agent.mjs
node yivpn-agent.mjs up --port 10808

Every YIVPN desktop, mobile, and CLI build includes 90 active minutes per day free (resetting daily at 16:00 UTC / 00:00 UTC+8). For full-time engineering teams, YiPro starts at $1.83/mo (billed annually at $21.99, or $2.99 monthly) and supports up to 5 concurrent devices.

FAQ

Why does my browser reach Anthropic and GitHub fine while Claude Code or git push times out in the terminal?

Standard OS 'System Proxy' settings only inform GUI apps that explicitly query WinINet or macOS Network Proxy APIs. Most Node.js, Go, Rust, and OpenSSH binaries connect directly to the network interface unless Layer-3 Global TUN is active or HTTPS_PROXY is exported.

Will Global TUN break my local Docker containers, Postgres port forwards, or LAN devices?

No. YIVPN's bundled sing-box 1.14.3 engine automatically bypasses loopback (127.0.0.0/8, ::1) and RFC1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) so local dev servers and LAN resources remain 100% direct.

Does the YIVPN Desktop MCP server access my source code or workspace files?

Never. The local MCP server binds strictly to 127.0.0.1:38410 and exposes only network status, node selection, and split-tunnel rule preview/rollback commands.

Start with 90 Minutes Free Every Day — Zero Sign-Up Required

Download YIVPN v1.0.6 with bundled offline sing-box core and Smart Split routing for Windows, macOS, and Android.

Download Official Apps → Compare Plans & Pricing