About

Imported from xiaoyuboi/cloudflare-tunnel-skill (SKILL.md). Install upstream with npx skills add xiaoyuboi/cloudflare-tunnel-skill. Copyright stays with the author (MIT).

Cloudflare Tunnel Agent Workflow

Name: cloudflare-tunnel
Author: xiaoyuboi

Help the user expose a local service through Cloudflare Tunnel. Choose the safest working mode:

Quick mode: temporary https://*.trycloudflare.com URL. Use for demos, previews, classroom sharing, and short-lived testing.
Named mode: fixed hostname such as app.example.com. Use when the user owns a Cloudflare-managed domain and needs a stable public URL.

Before running commands, identify:

Local service URL, usually http://localhost:<port> or https://localhost:<port>.
Exposure mode: quick or named.
Whether the service contains admin panels, tokens, private data, internal systems, or unauthenticated write APIs.

If the service is sensitive, pause and warn the user before exposing it. See references/security.md.

Paths and State

All scripts/... and references/... paths in this document are relative to this skill's install directory, not the user's project. When the working directory is the user's project, call the helper with its full installed path, for example:

python3 ~/.claude/skills/cloudflare-tunnel/scripts/tunnel_helper.py quick --url http://localhost:3000

The helper writes runtime state to .cloudflare-tunnel/ inside the current working directory, so run status and stop from the same directory where quick was started. If that directory is a git repository, make sure .cloudflare-tunnel/ is in its .gitignore before committing.

Mode Selection

Use quick mode when:

The user says temporary, demo, preview, share localhost, quick public link, or no domain.
The URL may change after restart.
The user does not need Cloudflare login.

Use named mode when:

The user asks for a fixed domain, stable public URL, webhook endpoint, or long-lived mapping.
The user has a Cloudflare account and a domain whose DNS is managed by Cloudflare.
The hostname should survive process restarts.

If unclear, default to quick mode for non-sensitive demos and ask only when exposing a sensitive service or creating a fixed hostname.

Required Checks

Check cloudflared:

cloudflared --version

Verify the local service before creating a tunnel:

curl -I http://localhost:<PORT>

Treat 200, 301, 302, 304, 401, and 403 as evidence that the service is reachable. Investigate connection failures before starting a tunnel.

Quick Mode

Read references/quick-tunnel.md when the user wants a temporary public URL.

Preferred helper:

python3 scripts/tunnel_helper.py quick --url http://localhost:<PORT>

The helper starts cloudflared in the background, waits for a trycloudflare.com URL, writes state under .cloudflare-tunnel/, and prints JSON with the public URL.

Helper behavior worth knowing:

If a quick tunnel for the same local URL is already running, it is reused ("reused": true). A running tunnel for a different local URL is stopped and replaced.
Transient api.trycloudflare.com failures are retried up to 3 times automatically.
verify falls back to DNS-over-HTTPS when the system resolver cannot resolve a fresh trycloudflare.com hostname (common behind fake-IP proxy DNS). DNS propagation can take one or two minutes; retry verify before treating the tunnel as broken.

Manual fallback:

printf '' > /tmp/cloudflared-empty.yml
cloudflared --config /tmp/cloudflared-empty.yml tunnel --no-autoupdate --protocol http2 --url http://localhost:<PORT>

Wait for both:

https://*.trycloudflare.com in the output
at least one Registered tunnel connection log line

Then verify:

python3 scripts/tunnel_helper.py verify --url https://xxxx.trycloudflare.com

Stop a helper-started tunnel:

python3 scripts/tunnel_helper.py stop

Named Mode

Read references/named-tunnel.md when the user wants a fixed domain.

Typical locally-managed CLI flow:

cloudflared tunnel login
cloudflared tunnel create <TUNNEL_NAME>
cloudflared tunnel route dns <TUNNEL_NAME> <HOSTNAME>

Create a config:

python3 scripts/tunnel_helper.py named-config \
  --name <TUNNEL_NAME> \
  --hostname <HOSTNAME> \
  --url http://localhost:<PORT>

Run:

cloudflared tunnel --config .cloudflare-tunnel/<TUNNEL_NAME>.yml run <TUNNEL_NAME>

Named mode may require an interactive browser login. Do not paste, print, commit, or store Cloudflare tokens outside the user's local Cloudflare config.

Output

After success, return:

Public URL
Local URL
Mode used
How to stop the tunnel
A short temporary/stability warning for quick mode

Example:

Public URL: https://xxxx.trycloudflare.com
Local URL: http://localhost:3000
Mode: quick
Stop: python3 scripts/tunnel_helper.py stop

This is a temporary Quick Tunnel URL. It stops working if cloudflared exits, the computer sleeps, or the network disconnects.

Troubleshooting

Use references/troubleshooting.md for:

no public URL in logs
404 from the tunnel
502 / Bad Gateway
self-signed local HTTPS
phone cannot open the link
named tunnel DNS or login failures

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/xiaoyuboi-cloudflare-tunnel-skill-cloudflare-tunnel/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

xiaoyuboi-cloudflare-tunnel-skill-cloudflare-tunnel.ocm.jsonjson

{
  "ocm": "1",
  "id": "xiaoyuboi-cloudflare-tunnel-skill-cloudflare-tunnel",
  "kind": "skill",
  "name": "cloudflare-tunnel",
  "description": "Use when a user wants to expose a local HTTP/HTTPS service to the public internet with Cloudflare Tunnel. Supports temporary Quick Tunnel URLs for previews and named tunnels with fixed custom domains for stable public mapping.",
  "publisher": "xiaoyuboi",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "cloudflare",
      "tunnel",
      "cloudflared",
      "localhost",
      "public-url",
      "preview",
      "custom-domain",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Use when a user wants to expose a local HTTP/HTTPS service to the public internet with Cloudflare Tunnel. Supports temporary Quick Tunnel URLs for previews and named tunnels with fixed custom domains for stable public mapping."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/xiaoyuboi/cloudflare-tunnel-skill",
      "path": "SKILL.md",
      "ref": "1f4eebaaf3baa5e1d9fb41f38cf74348f03f0ec9",
      "url": "https://github.com/xiaoyuboi/cloudflare-tunnel-skill/blob/1f4eebaaf3baa5e1d9fb41f38cf74348f03f0ec9/SKILL.md",
      "key": "xiaoyuboi/cloudflare-tunnel-skill/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Cloudflare Tunnel Agent Workflow\n\nHelp the user expose a local service through Cloudflare Tunnel. Choose the safest working mode:\n\n- **Quick mode**: temporary `https://*.trycloudflare.com` URL. Use for demos, previews, classroom sharing, and short-lived testing.\n- **Named mode**: fixed hostname such as `app.example.com`. Use when the user owns a Cloudflare-managed domain and needs a stable public URL.\n\nBefore running commands, identify:\n\n1. Local service URL, usually `http://localhost:<port>` or `https://localhost:<port>`.\n2. Exposure mode: quick or named.\n3. Whether the service contains adm",
  "cost": {
    "context_tokens": 1277
  }
}

Fetch it by URL: GET /api/v1/registry/xiaoyuboi-cloudflare-tunnel-skill-cloudflare-tunnel/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.