Tailscale CLI Skill

An Agent Skills-compatible package for safe, comprehensive management of Tailscale Funnel through the local Tailscale CLI.

The skill covers the complete Funnel lifecycle while adding safeguards around operations where the native CLI can affect more configuration than its command name suggests.

Highlights

• Inspect background public Funnel routes and private Serve handlers
• Expose HTTP/HTTPS backends, files, directories, static text, and Unix sockets
• Configure path-based HTTPS routing
• Manage raw TCP and TLS-terminated TCP forwarding
• Configure PROXY protocol v1/v2
• Disable one exact route without accidentally removing sibling paths
• Guard all-path removal and shared Serve/Funnel reset operations
• Detect when enabling Funnel would make existing private Serve handlers public
• Dry-run every mutation by default
• Parse and summarize native status JSON

Requirements

• Python 3.10 or newer
• A local tailscale CLI with Funnel support
• Tailscale 1.52 or newer recommended
• A connected tailnet with MagicDNS, HTTPS, and Funnel policy permissions configured

The wrapper uses only the Python standard library.

Install

Using the Skills CLI:

npx skills add 1am2syman/tailscale-cli-skill --skill tailscale-funnel

Install globally:

npx skills add 1am2syman/tailscale-cli-skill --skill tailscale-funnel --global

For Pi, you can also clone it directly into the global skill directory:

git clone https://github.com/1am2syman/tailscale-cli-skill.git \
  ~/.pi/agent/skills/tailscale-funnel

Quick Start

cd skills/tailscale-funnel
python3 scripts/funnelctl.py check
python3 scripts/funnelctl.py inspect

Plan a persistent HTTPS Funnel without changing anything:

python3 scripts/funnelctl.py on --bg --https 443 --set-path /api localhost:3000

Execute after approving the exact public exposure:

python3 scripts/funnelctl.py on --execute --bg \
  --https 443 --set-path /api localhost:3000

Remove only /api:

python3 scripts/funnelctl.py off --execute \
  --https 443 --set-path /api

Remove only the root route:

python3 scripts/funnelctl.py off --execute \
  --https 443 --set-path /

Safety Model

Funnel makes local resources reachable from the public internet.

• on, off, and reset are dry-runs unless --execute is supplied.
• HTTPS removal requires an exact --set-path; root is represented by /.
• Removing every HTTPS path requires --all-paths --confirm-all-paths.
• Enabling Funnel on a private Serve port is blocked unless the user explicitly supplies --allow-publicize-private-port.
• Native tailscale funnel reset clears the shared ServeConfig, including private Serve routes. Execution therefore requires --confirm-serve-and-funnel.
• Port 0 is rejected because native Tailscale can interpret it as an unset mode and fall back to HTTPS/443.
• Foreground Funnel sessions are not reported by native status output; the skill calls this out explicitly.

Read skills/tailscale-funnel/SKILL.md for the complete agent workflow and skills/tailscale-funnel/references/cli-reference.md for detailed CLI behavior.

Test

Tests use synthetic configuration and harmless binaries; they do not modify live Tailscale configuration.

python3 skills/tailscale-funnel/scripts/test_funnelctl.py -v

Project Layout

skills/tailscale-funnel/
├── SKILL.md                     Agent instructions and safety workflow
├── scripts/funnelctl.py         Safe Funnel CLI wrapper
├── scripts/test_funnelctl.py    Regression tests
└── references/cli-reference.md  Detailed native CLI semantics

Important Native Tailscale Behaviors

• Funnel and Serve share the same underlying configuration.
• The most recent Serve/Funnel command determines whether a listener port is private or public.
• Omitting --set-path from an HTTPS off command selects all handlers on that port.
• tailscale funnel reset clears both Funnel and Serve configuration in Tailscale v1.98.8.
• Native status reports background configuration, not foreground Funnel sessions.

Review every planned command before adding --execute.