dotfiles/home/.config/opencode/skills/cloudflared/SKILL.md

---
name: cloudflared
description: Use when the user asks to expose a local server to the internet, share a localhost URL publicly, test a webhook from a third-party, demo a local dev server to someone else, or get a public HTTPS URL for a port on this machine. Triggers on keywords like "cloudflared", "tunnel", "expose localhost", "public URL", "share local server", "webhook test", "ngrok alternative", "quick tunnel". Installs and runs `cloudflared` to put a localhost port on the public internet in one command.
---

# cloudflared — expose localhost to the world

Use this when the user needs a public HTTPS URL pointing at a port on this machine — for demos, webhook callbacks, or letting someone else hit a local server. One command, no account, no firewall changes.

## Install (first use)

If `cloudflared` is not on PATH:

```bash
brew install cloudflared          # macOS
# or: sudo apt install cloudflared       # Debian/Ubuntu (or download the .deb from github.com/cloudflare/cloudflared)
# or: winget install Cloudflare.cloudflared   # Windows
```

Verify: `cloudflared --version`.

## Quick tunnel (no account, no config)

The fastest path — gives you a random `https://<random>.trycloudflare.com` URL instantly:

```bash
cloudflared tunnel --url http://localhost:3000
```

Output contains a line like:

```
+--------------------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
|  https://example-words-tomorrow.trycloudflare.com                                          |
+--------------------------------------------------------------------------------------------+
```

Share that URL. The tunnel stays up as long as the process runs; kill it with Ctrl-C. No Cloudflare account needed. Random URL each run.

## Named tunnel (stable URL, requires account)

For a persistent hostname you can point clients/webhooks at repeatedly:

```bash
cloudflared tunnel login                       # browser auth, one-time
cloudflared tunnel create my-tunnel            # creates tunnel UUID
cloudflared tunnel route dns my-tunnel dev.example.com   # bind a hostname to it
```

Then run it with a config file `~/.cloudflared/config.yml`:

```yaml
tunnel: <tunnel-UUID>
credentials-file: /Users/<you>/.cloudflared/<tunnel-UUID>.json

ingress:
  - hostname: dev.example.com
    service: http://localhost:3000
  - service: http_status:404
```

```bash
cloudflared tunnel run my-tunnel
# or as a service:
sudo cloudflared service install        # macOS/Linux daemon
```

## Common patterns

| Goal | Command |
|---|---|
| Expose port 3000 with random URL | `cloudflared tunnel --url http://localhost:3000` |
| Expose a different local port | `cloudflared tunnel --url http://localhost:8080` |
| Expose HTTPS local server | `cloudflared tunnel --url https://localhost:3000` |
| Point a hostname at local server | named tunnel + `route dns` (above) |
| Run named tunnel in background | `cloudflared tunnel run my-tunnel &` or `cloudflared service install` |
| TCP port (e.g. SSH) | `cloudflared tunnel --url tcp://localhost:22` (needs named tunnel + `cloudflared access` client) |

## When to use

- "Give me a public URL for this local server" / "share this with my teammate"
- "I need to test a Stripe/GitHub/Slack webhook hitting my local machine"
- "Demo the dev server without deploying"
- "ngrok alternative" / "expose localhost"

## When NOT to use

- Production ingress → set up a real CDN/reverse proxy; quick tunnels are for dev/demo
- Internal-only access on the same machine → just use `localhost:PORT`
- Long-running stable hostnames without a Cloudflare account → quick tunnels are random and not persistent; use a named tunnel or a different tool

## Gotchas

- Quick tunnel URLs are random per run and can take 10-30s to become reachable after the banner prints.
- Cloudflare's free tier is fine for dev; rate limits and TOS apply to high-volume production traffic.
- If the local server binds to `127.0.0.1` only, that's fine — cloudflared connects from the same machine.
- Webhooks that verify SSL: the `*.trycloudflare.com` URL is real HTTPS with a valid cert, so verifiers pass.

## Source

Referenced in https://x.com/heyshruti7/status/2069083108092350823 — "cloudflared — expose localhost to the world with one prompt. Demo links in seconds."