| name | funnel-config |
| description | Manage Tailscale Funnel routes. Use when configuring tunnels or external HTTPS access. |
Tailscale Funnel Route Management
Discover Current State
tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'
tailscale funnel status
lsof -i -P -n | grep LISTEN | grep -E ':(8080|3000|3030|5000)'
Add a Service Route
tailscale funnel --bg <port>
tailscale serve --bg --set-path /<path> http://localhost:<port>
Rule: Routes coexist. Adding a root route does NOT remove sub-path routes. Adding a sub-path does NOT remove the root route.
Remove a Route
tailscale funnel --https=443 off
tailscale serve --https=443 --set-path /<path> off
Health Check
After any route change, verify both local and external:
HOSTNAME=$(tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//')
curl -s --max-time 5 http://127.0.0.1:<port>/health
curl -s --max-time 10 "https://${HOSTNAME}/<path>" -o /dev/null -w "%{http_code}\n"
Troubleshooting
| Symptom | Cause | Fix |
|---|
| External returns nothing | Funnel not active | tailscale funnel --bg <port> |
| External returns 502 | Service not running on that port | Start the service, check lsof -i :<port> |
| Route disappeared after restart | Funnel routes persist, but tailscale serve routes may not | Re-add with tailscale serve --bg --set-path ... |
| New route killed existing service | Won't happen — routes coexist | Verify with tailscale funnel status |
| GitHub webhooks not arriving | Hostname mismatch or funnel off | Check tailscale funnel status, compare with webhook URL |
Principles
- One service per path. Never route two services to the same path.
- Prefer sub-paths for non-primary services to avoid root conflicts.
- Always verify with external curl after changes — local success doesn't prove funnel works.
- Funnel requires Tailscale Funnel to be enabled on the tailnet (ACL policy).
