macos-tailscale-debug

name	macos-tailscale-debug
description	Debug macOS Tailscale connectivity issues, especially exit-node failures where browsers break but terminal networking still works. Use when Tailscale exit node, DNS, routing, system proxy, Surge, Clash, or localhost proxy hijacking are plausible causes on macOS.

macOS Tailscale Debug

Use this skill for macOS-specific Tailscale troubleshooting. It is optimized for the failure mode where:

• Tailscale exit node is enabled
• ping and curl still work in Terminal
• Browsers fail instantly or show an empty/progress-bar-only load

That pattern usually means app-layer proxy interference, not a dead exit node.

Workflow

1. Confirm the split:

   • Terminal works: ping 8.8.8.8, ping google.com, curl -4/-6 -I https://example.com
   • Browser fails
   • If both browser and terminal fail, skip the proxy-first path and inspect routing and the exit node itself.

2. Capture state without disrupting the session:

   • If toggling exit node would break the current remote session, do not toggle it yourself.
   • Ask the user to enable the broken state and run scripts/collect-exitnode-debug.sh.
   • Read references/commands.md for the minimal command set.

3. Check for proxy hijack first:

   • Inspect scutil --proxy.
   • On macOS, browsers obey system proxy settings more consistently than ping or plain curl.
   • If HTTPProxy, HTTPSProxy, or SOCKSProxy point to 127.0.0.1 or another localhost listener, treat that as the primary suspect.

4. Check whether the proxy is attached to the Tailscale network service:

   • Inspect networksetup -getwebproxy Tailscale
   • Inspect networksetup -getsecurewebproxy Tailscale
   • Inspect networksetup -getsocksfirewallproxy Tailscale
   • If needed, inspect /Library/Preferences/SystemConfiguration/preferences.plist to confirm that the Tailscale service or current network set carries stale proxy settings.

5. Identify the owner of the localhost proxy:

   • Typical candidates are Surge, Clash, Cisco clients, or similar local agents.
   • Compare localhost port numbers against installed tools and configs.
   • If the ports match a local proxy app, verify whether the app previously enabled system proxy for the Tailscale service.

6. Remediate only the broken layer:

   • If terminal connectivity is already good, do not rewrite Tailscale routes or server config first.
   • Turn off HTTP, HTTPS, and SOCKS proxy on the Tailscale network service.
   • Keep the exit node unchanged while testing.

7. Re-test:

   • Reconnect Tailscale if needed.
   • Re-enable exit node.
   • Re-test browser and scutil --proxy.

Decision Rules

• ping works, curl works, browser fails, and scutil --proxy shows localhost proxy: root cause is almost certainly local proxy interception on macOS.

• ping works but curl fails for both IPv4 and IPv6: investigate DNS, TLS, MTU, or exit-node forwarding before blaming the browser.

• Both terminal and browser fail only when exit node is on: inspect server-side Tailscale exit-route advertisement, forwarding, NAT, IPv6, and default route behavior.

Safe Ops

• Do not enable or disable exit node yourself if doing so would sever the current control session.
• Prefer state capture first, remediation second.
• Change the Tailscale network service proxy settings before changing Wi-Fi-wide settings when the issue is specific to exit-node mode.

References

• references/commands.md: commands and interpretation
• references/diagnosis-playbook.md: symptom-to-root-cause decision tree
• references/case-study.md: real incident summary
• scripts/collect-exitnode-debug.sh: one-shot debug collection