Cloudflare Tunnel

Expose local development ports, containers, and multi-service architectures to the public internet securely using Cloudflare Tunnel without opening firewall ports.

Purpose & Mental Model

AI agents often develop applications inside isolated environments (Docker containers, cloud VMs, WSL, local dev servers) that cannot be directly reached by external services, physical mobile devices, or remote browser controllers like ego-browser.

Cloudflare Tunnel establishes an outbound encrypted connection (QUIC or HTTP/2 over port 7844) from your local environment to Cloudflare's global edge network:

1. Quick Tunnels (try.cloudflare.com): Zero-configuration, ephemeral public HTTPS URLs. No Cloudflare account, API tokens, or DNS required. Features native agent support via --output json. Best for ad-hoc agent testing, webhooks, and remote browser validation.
   • Protected Quick Tunnels (--allowed-mail): Supported in cloudflared >= 2026.10.0 (Cloudflare Birthday Week). Allows locking the tunnel behind email OTP authentication without an account or dashboard configuration.
   • Agent Trade-offs & Limitations:
     • Pros: Zero secret leakage risk and instant one-command setup.
     • Cons: Subdomains rotate on restart (*.trycloudflare.com), capped at 200 concurrent in-flight requests (returns HTTP 429), and does not support Server-Sent Events (SSE) (text/event-stream stalls or drops tokens).
     • Headless Wall: --allowed-mail requires an interactive browser session to enter the OTP code; it blocks headless API clients, curl, and automated agent-to-agent interactions.
2. Named Tunnels (Production & Persistent): Persistent, authenticated tunnels tied to custom domains and Cloudflare Zero Trust Access policies.
   • Agent Suitability: Ideal for long-lived environments, automated agent-to-agent programmatic access via Cloudflare Access Service Tokens, high-concurrency workloads, and streaming SSE (LLM chat streaming).
   • Native Ingress: Eliminates the need for a reverse proxy like unified-proxy.mjs by natively routing multiple services (e.g. / -> frontend, /api -> backend) in config.yml.
3. Same-Origin Unified Proxy Pattern: When testing Single Page Applications (React, Expo Web, Vite) that consume local APIs (Supabase, Express, FastAPI) over Quick Tunnels, running a lightweight unified reverse proxy on one port eliminates browser Mixed Content (https -> http) and CORS blocks.

The Mandatory 3-Gate Verification Rule

Never report a tunnel URL to a user or open a browser on a remote machine until all 3 gates pass:

┌────────────────────────────────────────────────────────────────────────┐
│ Gate 1: Local Origin Health                                            │
│ curl -s -f http://127.0.0.1:<PORT>/<path>  ──> Must return HTTP 200    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ Gate 2: Global DNS Publication (60s SOA Negative Cache Window)         │
│ dig @1.1.1.1 +short <subdomain>            ──> Must return Edge IPs    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ Gate 3: Target Client Reachability (Zero False Positives)              │
│ ssh <client> "curl -s -o /dev/null -w '%{http_code}' <URL>"  ──> 200 OK│
└────────────────────────────────────────────────────────────────────────┘

Decision Tree

flowchart TD
    Start["Task: Expose local service"] --> NeedAuth{"Requires custom domain or auth?"}
    
    NeedAuth -->|No: Ad-hoc / Testing| TargetOrigin{"Origin Type?"}
    NeedAuth -->|Yes: Persistent / Production| NamedTunnel["Read references/named-tunnels.md
Use cloudflared tunnel run --token"]
    
    TargetOrigin -->|UI Design / Theme / Hydration Fidelity| BuiltInstance["Build production local instance
(e.g., pnpm preview on 8788)"]
    TargetOrigin -->|Rapid Loop / API Debugging| DevInstance["Run dev server (e.g., 4321 / 3000)"]

    BuiltInstance --> IsFullStack{"SPA calling local backend API?"}
    DevInstance --> IsFullStack

    IsFullStack -->|Yes: Web + API| Unified["Read references/same-origin-proxy.md
Run scripts/unified-proxy.mjs
Then tunnel proxy port"]
    IsFullStack -->|No: Single Port Service| QuickTunnel["Read references/quick-tunnels.md
Run scripts/quick-tunnel.sh --port <P>"]

    QuickTunnel --> VerifyTarget{"Client / Remote Target?"}
    Unified --> VerifyTarget
    
    VerifyTarget -->|MacBook / Remote Host| TargetProbe["Read references/remote-testing.md
Execute Gate 3: Target Client Probe"]
    VerifyTarget -->|ego-browser / Mobile| Remote["Read references/remote-testing.md
Drive CDP with 390x844 viewport"]
    VerifyTarget -->|Standard webhook| Done["Inspect public trycloudflare.com URL"]

Minimal Reading Sets

Load only the reference files required for your specific path:

Quick Starts

1. Expose a Single Local Port with Process Group Isolation

Using the bundled automated script:

# Starts tunnel detached, extracts URL, verifies DNS (auto-handles macOS/Linux)
bash scripts/quick-tunnel.sh --port 8080 --out /tmp/tunnel-url.txt

Or via raw CLI with agent-safe process isolation and native --output json:

# 1. Clean previous state (DO NOT delete ~/.cloudflared which stores production certs!)
rm -f /tmp/cloudflared-8080.log /tmp/cloudflared-8080.pid

# 2. Launch detached daemon (auto-fallback across Linux setsid / macOS nohup)
CF_ARGS=(tunnel --url "http://127.0.0.1:8080" --protocol auto --logfile /tmp/cloudflared-8080.log --pidfile /tmp/cloudflared-8080.pid --no-autoupdate --output json)
if command -v setsid &>/dev/null; then
  setsid nohup cloudflared "${CF_ARGS[@]}" </dev/null >/dev/null 2>&1 &
else
  nohup cloudflared "${CF_ARGS[@]}" </dev/null >/dev/null 2>&1 &
fi

# 3. Extract URL (or parse json events)
sleep 3
TUNNEL_URL=$(grep -o 'https://[-a-z0-9.]*trycloudflare.com' /tmp/cloudflared-8080.log | tail -n 1)

2. The 2-Step DNS Handshake (Preventing 60-Second Negative-Cache Delays)

When a new *.trycloudflare.com subdomain is assigned, public authoritative edge DNS requires 1–3s to propagate. Querying client/local DNS (e.g. Tailscale MagicDNS 100.100.100.100) prematurely causes an immediate 60-second RFC 2308 negative-cache lock (Cloudflare SOA minimum TTL).

HOST_ONLY=$(echo "$TUNNEL_URL" | sed -E 's#^https?://##')

# Step A: Wait for global authoritative DNS (1.1.1.1 & 8.8.8.8)
for i in {1..15}; do
  IP1=$(dig @1.1.1.1 +short "$HOST_ONLY" 2>/dev/null | tail -n 1)
  IP2=$(dig @8.8.8.8 +short "$HOST_ONLY" 2>/dev/null | tail -n 1)
  if [[ -n "$IP1" && -n "$IP2" ]]; then break; fi
  sleep 1
done

# Step B: Flush client DNS cache before first query
if command -v dscacheutil &>/dev/null; then
  dscacheutil -flushcache 2>/dev/null || true
fi

# Step C: Verify directly from target client machine (Target Perspective Gate)
# e.g., ssh <client> "curl -s -L -o /dev/null -w '%{http_code}' -m 5 '$TUNNEL_URL'" # Returns 200 or 3xx redirect

3. Full-Stack Web + API (Unified Same-Origin Proxy)

Solves the browser Mixed Content block where an HTTPS tunnel cannot talk to http://127.0.0.1:<api-port>:

# 1. Start unified proxy on port 8099
node scripts/unified-proxy.mjs \
  --port 8099 \
  --static /tmp/web-dist \
  --api-port 55721 \
  --api-prefixes /api/,/auth/,/rest/,/functions/ &

# 2. Expose the unified proxy with isolated daemon
bash scripts/quick-tunnel.sh --port 8099 --out /tmp/public-app.txt

Key Patterns

Pattern A: Cross-Platform Process-Isolated Daemon Spawning

Decouple the tunnel daemon from the tool invocation process group:

CF_ARGS=(tunnel --url "http://127.0.0.1:${PORT}" --protocol auto --logfile "$LOGFILE" --output json)
if command -v setsid &>/dev/null; then
  setsid nohup cloudflared "${CF_ARGS[@]}" </dev/null >/dev/null 2>&1 &
else
  nohup cloudflared "${CF_ARGS[@]}" </dev/null >/dev/null 2>&1 &
fi

Pattern B: Protocol Negotiation (auto vs http2)

While Named Tunnels default to auto, ad-hoc quick tunnels (cloudflared tunnel --url ...) internally default to quic unless --protocol auto is explicitly supplied. Always pass --protocol auto so cloudflared automatically falls back to HTTP/2 over TCP port 7844 if UDP is blocked by firewalls:

# Recommended: Auto-negotiate QUIC with HTTP/2 fallback
cloudflared tunnel --protocol auto --url http://127.0.0.1:8080

# Or force pure HTTP/2 if UDP 7844 is strictly prohibited:
cloudflared tunnel --protocol http2 --url http://127.0.0.1:8080

Pattern C: Clean Teardown (Preserving Named Tunnels)

Never run a blunt pkill -f "cloudflared tunnel" or delete ~/.cloudflared/ during quick tunnel cleanup! That kills production named tunnels and destroys credentials. Clean only ad-hoc quick tunnel instances and temporary logs:

# Safely kill only ad-hoc quick tunnels (Preserves named tunnels):
pkill -f "cloudflared tunnel --url" || true
rm -f /tmp/cloudflared*

Common Pitfalls

Reference Routing Table

Every topic has an exhaustive reference document. Read the relevant file when performing detailed work:

Verification & Orphan Check

Validate that the skill follows the specification:

for f in $(find references -name '*.md' -type f); do grep -q "$(basename "$f")" SKILL.md || echo "ORPHAN: $f"; done

Must return 0 orphans.