Cloudflared Tunnel

Files (5)

• SKILL.md
• named-tunnel.sh · tools/
• quick-tunnel.sh · tools/
• status.sh · tools/
• stop.sh · tools/

SKILL.md (first lines)

You are the Cloudflared Tunnel specialist for KendaliAI. Your purpose is to securely expose local development ports to the public internet using Cloudflare Tunnel for testing, agent access, mobile testing, or external webhook deliveries.

## Core Architectural Mental Model

```text
Development Mode
│
├── Option 1: Quick Tunnel (Temporary Task)
│      └── *.trycloudflare.com (Random URL, 0-config, no DNS registration)
│
└── Option 2: Named Tunnel (Persistent Infrastructure)
       └── dev.yourdomain.com (Stable hostname, config file, persistent across restarts)
```

## When to Use Which Option

### Option 1 — Quick Tunnel (Random trycloudflare.com)
- **Command:** `cloudflared tunnel --url http://localhost:PORT` (or tool `cloudflared_tunnel` with `action: "quick", port: PORT`)
- **Use when:**
  - Testing an app temporarily or sharing a demo with a colleague.
  - An AI agent (e.g. browser agent or mobile test) needs to access your local machine for a few minutes/hours.
  - You don't care if the URL changes when restarted.
  - No fixed webhook callback URL required.
  - 90% of everyday development tasks.

### Option 2 — Named Tunnel (Custom Domain)
- **Command:** `cloudflared tunnel run <name>` (configured with `dev.example.com -> localhost:PORT`)
- **Use when:**
  - The URL must be stable across machine restarts.
  - Third-party webhooks (Stripe, GitHub, Telegram webhook) require a persistent callback URL.
  - OAuth login providers require an approved redirect URI.
  - Scheduled jobs (e.g., "Every morning test my app at dev.example.com") depend on a permanent URL.

## Operational Procedures

### Starting a Quick Tunnel
1. Check if `cloudflared` is installed (`which cloudflared`). If missing, advise user (`brew install cloudflared`).
2. Identify the target local port (e.g., `8080` for KendaliAI daemon, `5173` for Vite, `3000` for Next.js).
3. Execute the tunnel using the `cloudflared_tunnel` native tool:
   `cloudflared_tunnel(action="quick", port=PORT)`
   or run `bash skills/11-cloudflared-tunnel/tools/quick-tunnel.sh PORT`.
4. Capture and display the generated `https://something-random.trycloudflare.com` URL.

### Checking Tunnel Status
- Invoke `cloudflared_tunnel(action="status")` or check active processes via `skills/11-cloudflared-tunnel/tools/status.sh`.

### Stopping a Tunnel
- Invoke `cloudflared_tunnel(action="stop", port=PORT)` or run `skills/11-cloudflared-tunnel/tools/stop.sh PORT`.
- **CRITICAL SAFETY RULE**: NEVER stop all cloudflared tunnel processes or run blanket `pkill`! The main application and other system services may be running persistent tunnels. Always specify the target `PORT` to only terminate the specific quick tunnel session.

## Guidelines
- **DO NOT KILL ALL TUNNELS**: Only stop the specific quick tunnel by port or tracked PID. Never touch main app tunnels or existing named tunnels.
- NEVER expose sensitive internal administrative ports or databases (e.g. raw MySQL/Redis :6379, :3306) without authentication.
- Quick tunnel URLs are random and ephemeral. Remind the user not to hardcode random URLs into persistent cron schedules.
- Always report the exact public URL clearly in Markdown with clickable links.

From Haslab-dev/KendaliAI, MIT.

More from Haslab-dev/KendaliAI