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
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-providerSkill
- expo-local-shipSkill
- integration-by-batchesSkill
- setup-cloudflaredSkill
- ship-expo-cloudSkill
- ship-fastlaneSkill
- add-provider-mobileSkill
- expo-local-shipSkill
- integration-by-batches-mobileSkill
- ship-expo-cloudSkill
- ship-fastlaneSkill
- threadbase-designSkill
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
- Very specific: line 59
Place filled-in config.yml at ~/.cloudflared/config.yml.
- Distinctive: line 75
Always edit the SYSTEM profile path above.
- Distinctive: line 79
Check if cloudflared is already running as a service:
- Distinctive: line 84
If it is, add Metro as an ingress route to the SYSTEM profile config:
- Distinctive: line 98
Verify the tunnel reaches Metro:
≈ “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.
Files
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:
- Spins up a dummy HTTP listener on 8081 (so cloudflared doesn't exit).
- Launches cloudflared, waits for the
*.trycloudflare.comURL. - Kills the dummy listener.
- Starts Metro with
EXPO_PACKAGER_PROXY_URLset.
npm run dev:tunnel # JS-only
npm run dev:tunnel -- -c # clear Metro cache
DEVICE_UDID=<udid> npm run dev:tunnel:native # full native rebuildNamed tunnel (stable hostname)
CLOUDFLARED_TUNNEL_NAME=<name> npm run dev:tunnelOne-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.ymlEditing ~\.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 cloudflaredIf 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 lastRestart from Administrator PowerShell:
Restart-Service cloudflaredVerify the tunnel reaches Metro:
(Invoke-WebRequest -Uri "https://<your-metro-hostname>/status" -UseBasicParsing).Content
# Should return: packager-status:runningStart Metro:
$env:EXPO_PACKAGER_PROXY_URL="https://<your-metro-hostname>"; npx expo start --lanOption B — install a dedicated service
From Administrator PowerShell:
cloudflared --config "C:\path\to\repo\.cloudflared\config.example.yml" service installOption C — run manually (two terminals)
Terminal 1:
cloudflared tunnel --config "$env:USERPROFILE\.cloudflared\config.yml" runTerminal 2:
$env:EXPO_PACKAGER_PROXY_URL="https://<your-metro-hostname>"; npx expo start --lanNote: 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(fromschemeinapp.json), notexp+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
| Symptom | Fix |
| Tunnel returns 404 | Check you edited the SYSTEM profile config (not ~\.cloudflared\), then Restart-Service cloudflared |
packager-status:running locally but tunnel 404s | Service 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 tunnel | route dns <name> can silently pick up an existing CNAME; always use the UUID: cloudflared tunnel route dns <TUNNEL-ID> <hostname> |
| Service install fails silently | Requires Administrator — re-run from Admin terminal |
$env:VAR=true gives error on PowerShell | Always quote values: $env:VAR="true" |
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
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.

