vpn-localhost-fix

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

```bash
# 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:**

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

```bash
# 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)