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
Decision gist · record as of 2026-07-27
Tunnel Doctor diagnoses and resolves conflicts between Tailscale and proxy/VPN tools on macOS. 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.
Use it when
- Tunnel Doctor addresses Docker/container networking issues behind Tailscale and TUN proxies by checking whether the TUN interface is.
- Tunnel Doctor isolates this common split-brain scenario by distinguishing between network reachability (ping succeeds).
Verify before relying
Read SKILL.md below before installing (6 files). Open directory: indexed for reading, not audited.
Install
daymade/claude-code-skills/tunnel-doctor · repository language: Python
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Diagnose and resolve Tailscale conflicts with proxy/VPN tools on macOS”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill helps you troubleshoot connection problems with Windows App, Azure Virtual Desktop, and direct PC connections on macOS. It guides you through identifying whether your connection is using optimal UDP Shortpath or falling back to slower WebSocket transport, checks for VPN or proxy interference, and parses Windows App logs to uncover auth failures or protocol negotiation issues.
Troubleshoot Docker Hub connectivity problems in OrbStack by identifying whether failures stem from network routing, system proxy settings, or daemon configuration. The skill guides you through diagnostic checks, proxy setup, and daemon tuning to restore reliable image pulls.
This skill applies falsification-first methodology to network and streaming incidents where the obvious cause is likely a red herring. Rather than stacking assumptions, it guides you through layered isolation—testing the same request across different paths to pinpoint exactly which hop (client, CDN, proxy, or backend) is responsible. Use it for connection resets, SSE stalls, fixed-time drops, certificate errors, or LAN mysteries where symptoms like "works sometimes" or "fails after N seconds" point to multiple possible layers.
This skill runs evidence-first network diagnostics and optimization on macOS, starting with read-only measurements of speed, latency, jitter, and DNS performance. It protects VPN and proxy services by default, proposing only reversible changes like DNS A/B tests, service reordering, or AWDL toggling before applying them. Use it to identify bottlenecks in link quality, bufferbloat, DNS instability, or background traffic, then verify improvements with before-and-after measurements.
Pinggy Tunnel creates instant public URLs for local services using SSH reverse tunnels, with no daemon installation needed. Free tier offers 60-minute tunnels with random subdomains; Pro tier ($3/mo) adds persistent URLs and longer session times. Supports HTTP, HTTPS, TCP, and TLS tunneling with optional access controls like basic auth, bearer tokens, IP whitelisting, and CORS.
This skill guides you through pivoting and tunneling strategies to reach internal networks from a compromised host during authorized penetration tests. It covers SSH port forwarding, SOCKS proxies, and specialized tools like Chisel, Ligolo-ng, and sshuttle, with a decision tree to select the right approach based on available access and network constraints.
More skills vpn-setup (MIT) · tunneling-and-pivoting (MIT) · Network Doctor (unlicensed) · web-preview (MIT) · orbstack-cli (MIT) · orbstack-best-practices (Apache-2.0)