tunnel-doctor
Tunnel Doctor isolates and resolves conflicts when Tailscale coexists with proxy/VPN tools like Shadowrocket, Clash, or Surge on macOS. It addresses route table corruption, environment variable misconfigurations, system proxy bypass issues, SSH double-tunneling, and VM/container proxy propagation problems—covering scenarios from browser 503 errors to Docker timeouts and WSL SSH access.
Tunnel Doctor diagnoses and resolves conflicts between Tailscale and proxy/VPN tools on macOS.
AI-generated summary based on this skill's SKILL.md
Install
daymade/claude-code-skills/tunnel-doctor · repository language: Python
git clone https://github.com/daymade/claude-code-skills
cp -r claude-code-skills/tunnel-doctor ~/.claude/skills/tunnel-doctornpx skillfed install daymade/claude-code-skills/tunnel-doctorFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
Why does Tailscale SSH not work on macOS when a proxy tool is active?
Tunnel Doctor helps diagnose SSH failures over Tailscale when proxy/VPN tools like Shadowrocket or Clash are running. Common causes include route table corruption, DNS hijacking by the TUN interface, or environment variables (http_proxy, https_proxy) forcing SSH traffic through the proxy instead of Tailscale's direct path. Tunnel Doctor identifies whether the issue is a resolver stall, a double-tunnel loop, or a skip-proxy misconfiguration, then guides you to disable the conflicting proxy rule or adjust Tailscale's DNS settings.
How can I fix docker pull timing out behind a VPN and Tailscale?
Tunnel Doctor addresses Docker/container networking issues behind Tailscale and TUN proxies by checking whether the TUN interface is hijacking DNS queries or blocking container-to-registry connections. If docker pull times out, Tunnel Doctor helps you verify that the container's resolver isn't stalled on 198.18.x.x virtual IPs, confirm the TUN isn't breaking the MTU (often 1280), and ensure environment variables aren't leaking proxy settings into the container runtime. It also detects OrbStack or WSL-specific route conflicts.
What should I do if tailscale ping works but SSH times out?
Tunnel Doctor isolates this common split-brain scenario by distinguishing between network reachability (ping succeeds) and application-layer routing (SSH hangs). The issue typically stems from DNS resolver stalls—SSH hangs 60 seconds resolving the hostname because the TUN DNS hijack is failing—or from http_proxy environment variables forcing SSH through a proxy relay that breaks Tailscale's direct connection. Tunnel Doctor checks both the resolver state and your shell environment, then recommends unset http_proxy or adjusting your proxy tool's skip-proxy rules.
How do I resolve Git push failures with HTTP relay errors over Tailscale?
Tunnel Doctor debugs Git operations failing over Tailscale with TUN proxies by examining whether curl works (indicating network access) but Git fails (indicating proxy/DNS misconfiguration). If git push returns an HTTP relay error, Tunnel Doctor checks for double-tunnel loops (ProxyCommand chaining), environment variable leaks, or DNS resolver stalls. It also detects whether your proxy tool's skip-proxy list includes your Git server's hostname, and whether Tailscale's exit node or subnet routing is interfering with the relay path.
Why does curl work but the browser returns a 503 error behind Tailscale?
Tunnel Doctor identifies tool-specific proxy bypass failures when curl succeeds but the browser returns 503. This typically means the browser is using the system proxy settings (which may route through a TUN tool like Surge or Clash) while curl is not, or vice versa. Tunnel Doctor checks whether Tailscale's DNS is being hijacked for browser requests, whether the proxy tool's skip-proxy list excludes your target domain, and whether environment variables are inconsistently applied across tools.
How can I safely set up remote development over Tailscale with proxy tools?
Tunnel Doctor supports safe remote development setup by helping you configure Tailscale alongside proxy/VPN tools without conflicts. It recommends explicit skip-proxy rules for Tailscale's CGNAT range and your Git/SSH servers, verifies DNS resolver health (avoiding 198.18 stalls), confirms MTU settings for container networking, and checks ProxyCommand chains for double-tunnel loops. Tunnel Doctor also covers WSL and macOS-specific configurations, ensuring SSH, Git, and Docker all route correctly through Tailscale while other traffic uses your proxy tool.
SKILL.md
rendered from the published skill — quoted content, verbatim
Tunnel Doctor
Diagnose and fix conflicts when Tailscale coexists
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 6 files
tunnel-doctor/.security-scan-passed
tunnel-doctor/SKILL.md
tunnel-doctor/references/dns_resolver_chain_stall.md
tunnel-doctor/references/proxy_conflict_reference.md
tunnel-doctor/references/windows_host_tun_wsl_cascade.md
tunnel-doctor/scripts/quick_diagnose.py