fix: add preflight check for funnel on tailscale

[Anshuman71]

Summary

Fixes portless --funnel hanging before the child process starts when Tailscale prerequisites are missing.

I was using portless + tailscale combination to test a Slack bot from Next.js app. The --funnel command would always hang at localhost setup and won't even start the Next.js app. After some debugging, I realized my tailnet is not configured to use a funnel, and enabling that solved my issue. So, I've added a preflight check that provides actionable feedback to users who encounter the same issue.

Repro

1. Disable Funnel for the current tailnet/node.
2. Run:

portless run --funnel next dev"

Before this change, portless printed the local URL, then blocked during tailscale funnel registration. The child command never started and no actionable error was shown.

Fix

• Preflight Tailscale readiness before route registration.
• Require Tailscale HTTPS certificates for --tailscale and --funnel.
• Require Funnel capability for --funnel.
• Surface actionable errors for missing HTTPS/Funnel settings.
• Keep a bounded Tailscale CLI timeout as a fallback.
• Update README, CLI help, and agent skill docs.

Test

pnpm --filter portless test -- tailscale.test.ts
pnpm --filter portless type-check
pnpm --filter portless build

Manual check:

portless run --funnel next dev"

With Funnel disabled, portless should fail before printing child-started.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
portless	Ready	Preview, Comment	May 4, 2026 8:23am