Awesome-omni-skill vpn-localhost-fix

Fix VPN proxy conflicts with local development tools. Use when apps like OpenCode Desktop, VS Code, or other Electron/Tauri-based applications fail to start or connect to their local servers when a VPN proxy is enabled. Symptoms include "Failed to spawn server" errors, connection refused to 127.0.0.1 ports, or apps hanging on startup. Supports Clash Verge and other system proxy VPNs on macOS.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/vpn-localhost-fix" ~/.claude/skills/diegosouzapw-awesome-omni-skill-vpn-localhost-fix && rm -rf "$T"

manifest: skills/development/vpn-localhost-fix/SKILL.md

source content

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

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:

Backup config:
```
cp verge.yaml verge.yaml.backup
```
Edit
```
verge.yaml
```
with the bypass settings above
Restart Clash Verge
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:

Restart the VPN application completely
Restart the affected application (OpenCode Desktop, etc.)
Check for multiple VPNs running simultaneously - disable extras
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)