agentleFS
RonenMarsRonenMars/threadbase-mobile/.agents/skills/setup-cloudflared/SKILL.md

setup-cloudflared

Skill4 starsChanged 2 days agoMITView on GitHub

Set up a Cloudflare tunnel to expose Metro (port 8081) over HTTPS for remote React Native / Expo dev. Covers macOS/Linux (quick + named tunnels via npm scripts) and Windows (system service with SYSTEM profile config). Use when the user wants to connect a phone to Metro over a tunnel, configure a stable hostname, add Metro to an existing cloudflared service, or troubleshoot tunnel routing issues.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Place filled-in config.yml at ~/.cloudflared/config.yml.

    line 59
  2. Distinctive:

    Always edit the SYSTEM profile path above.

    line 75
  3. Distinctive:

    Check if cloudflared is already running as a service:

    line 79
  4. Distinctive:

    If it is, add Metro as an ingress route to the SYSTEM profile config:

    line 84
  5. Distinctive:

    Verify the tunnel reaches Metro:

    line 98

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

setup-cloudflared

Sets up a Cloudflare tunnel to expose Metro bundler (port 8081) over HTTPS so a physical device can connect without sharing the same Wi-Fi.

How it works

EXPO_PACKAGER_PROXY_URL is set at Metro startup. Expo advertises that URL to the app instead of the local LAN IP. The app fetches its JS bundle through the tunnel — device and dev machine no longer need to share a network.

Key constraint: tunnel and Metro must run on the same machine (the tunnel proxies localhost:8081).

Project config files

  • .cloudflared/config.example.yml — committed template (like .env.example)
  • .cloudflared/config.yml — gitignored, real values for your machine

Copy the example, fill in tunnel ID and hostname, then follow the platform steps below.


macOS / Linux

Quick tunnel (no account, temporary URL)

npm run dev:tunnel handles everything automatically:

  1. Spins up a dummy HTTP listener on 8081 (so cloudflared doesn't exit).
  2. Launches cloudflared, waits for the *.trycloudflare.com URL.
  3. Kills the dummy listener.
  4. Starts Metro with EXPO_PACKAGER_PROXY_URL set.
npm run dev:tunnel                           # JS-only
npm run dev:tunnel -- -c                     # clear Metro cache
DEVICE_UDID=<udid> npm run dev:tunnel:native # full native rebuild

Named tunnel (stable hostname)

CLOUDFLARED_TUNNEL_NAME=<name> npm run dev:tunnel

One-time DNS setup:

cloudflared tunnel create <name>
# Use the UUID returned, not the name, to avoid routing to the wrong tunnel:
cloudflared tunnel route dns <TUNNEL-ID> <your-hostname>

Place filled-in config.yml at ~/.cloudflared/config.yml.


Windows (PowerShell)

The critical gotcha: SYSTEM profile config path

The cloudflared Windows service runs as SYSTEM. It reads its config from the SYSTEM profile — not your user profile:

C:\Windows\system32\config\systemprofile\.cloudflared\config.yml

Editing ~\.cloudflared\config.yml has no effect on the service. Always edit the SYSTEM profile path above.

Option A — add Metro to existing service (recommended)

Check if cloudflared is already running as a service:

sc.exe query cloudflared

If it is, add Metro as an ingress route to the SYSTEM profile config:

ingress:
  # ... existing routes ...
  - hostname: <your-metro-hostname>
    service: http://localhost:8081
  - service: http_status:404   # must stay last

Restart from Administrator PowerShell:

Restart-Service cloudflared

Verify the tunnel reaches Metro:

(Invoke-WebRequest -Uri "https://<your-metro-hostname>/status" -UseBasicParsing).Content
# Should return: packager-status:running

Start Metro:

$env:EXPO_PACKAGER_PROXY_URL="https://<your-metro-hostname>"; npx expo start --lan

Option B — install a dedicated service

From Administrator PowerShell:

cloudflared --config "C:\path\to\repo\.cloudflared\config.example.yml" service install

Option C — run manually (two terminals)

Terminal 1:

cloudflared tunnel --config "$env:USERPROFILE\.cloudflared\config.yml" run

Terminal 2:

$env:EXPO_PACKAGER_PROXY_URL="https://<your-metro-hostname>"; npx expo start --lan

Note: when setting env vars, $env:VAR=true (unquoted) fails — PowerShell tries to execute true as a command. Quote the value.

Kill Metro on Windows

npm run kill:metro uses a bash script and won't work on Windows:

$pid = (netstat -ano | Select-String ":8081.*LISTENING" | ForEach-Object { ($_ -split '\s+')[-1] } | Select-Object -First 1)
if ($pid) { taskkill /PID $pid /F }

Connecting from the dev-client app

Once Metro is running with EXPO_PACKAGER_PROXY_URL set, connect from the Threadbase dev-client app using the deep link:

exp+threadbase://expo-development-client/?url=https%3A%2F%2F<your-hostname>

Or tap Enter URL manually and enter:

https://<your-hostname>

Note: The scheme is exp+threadbase (from scheme in app.json), not exp+threadbase-mobile (the slug). Expo CLI may print the slug-based URL — if the app doesn't open, use the scheme-based URL above.

Initial bundle timing: the "Could not connect" error can appear if the phone connects before Metro finishes its first bundle. Wait for Metro to print Bundled, then tap Reload JS.


Troubleshooting

SymptomFix
Tunnel returns 404Check you edited the SYSTEM profile config (not ~\.cloudflared\), then Restart-Service cloudflared
packager-status:running locally but tunnel 404sService didn't restart after config change — run Restart-Service cloudflared as Administrator
cloudflared exits immediately (macOS/Linux)Port 8081 not open yet; npm run dev:tunnel handles this automatically
"Failed to get tunnel URL after 30s"Port 8081 in use — kill Metro first
Named tunnel routes to wrong tunnelroute dns <name> can silently pick up an existing CNAME; always use the UUID: cloudflared tunnel route dns <TUNNEL-ID> <hostname>
Service install fails silentlyRequires Administrator — re-run from Admin terminal
$env:VAR=true gives error on PowerShellAlways quote values: $env:VAR="true"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.