VPN Localhost Bypass Fix

Overview

This skill fixes issues where VPN system proxies interfere with local development tools and applications. When a VPN enables system-wide proxying, local connections (localhost/127.0.0.1) may be intercepted, preventing apps from connecting to their own backend servers.

Common symptoms:

• Electron/Tauri apps (OpenCode Desktop, VS Code) fail to start
• Error: Failed to spawn server or Connection refused to 127.0.0.1
• Apps work fine when VPN is disabled, fail when enabled

Root cause: VPN system proxy lacks bypass rules for localhost traffic.

---

Quick Diagnosis

Confirm the issue with these checks:

# Check if system proxy is enabled
scutil --proxy | grep "HTTPSEnable : 1"

# Check if localhost is in bypass list
scutil --proxy | grep "ExceptionsList"

If HTTPSEnable is 1 but ExceptionsList doesn't include localhost/127.0.0.1, use this skill.

---

Supported VPNs

Clash Verge (macOS)

Config file: ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/verge.yaml

Add/modify these settings:

use_default_bypass: true
system_proxy_bypass: localhost, 127.0.0.1, *.local, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

Steps:

1. Backup config: cp verge.yaml verge.yaml.backup
2. Edit verge.yaml with the bypass settings above
3. Restart Clash Verge
4. Verify: scutil --proxy | grep ExceptionsList

Other VPNs

Look for settings named:

• "Bypass List" / "例外列表" / "绕过规则"
• "Proxy Exclusions" / "Direct Connection"
• "Local addresses bypass"

Add: localhost, 127.0.0.1, *.local

---

Verification

After applying the fix:

# Verify bypass rules are active
scutil --proxy | grep -A 10 "ExceptionsList"

Expected output should include:

ExceptionsList : <array> {
  0 : 127.0.0.1
  1 : localhost
  2 : *.local
  ...
}

---

Standard Bypass Rules

Recommended bypass list for most users:

localhost, 127.0.0.1, *.local, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

| Entry | Purpose | |-------|---------| | localhost | Local hostname | | 127.0.0.1 | Loopback interface | | *.local | Bonjour/mDNS local domains | | 192.168.0.0/16 | Private network class C | | 10.0.0.0/8 | Private network class A | | 172.16.0.0/12 | Private network class B |

---

Troubleshooting

Problem: Still failing after adding bypass rules

Solutions:

1. Restart the VPN application completely
2. Restart the affected application (OpenCode Desktop, etc.)
3. Check for multiple VPNs running simultaneously - disable extras
4. Verify config file syntax (YAML for Clash)

Problem: Multiple VPNs with conflicting ports

Solution: Ensure each VPN uses different proxy ports (e.g., Clash: 7897)