Skip to content

Cloudflared Tunnel Setup

Cloudflared is the program that creates a public HTTPS URL pointing at your local G-Labs backend. PatchWork (hosted on Cloudflare Pages) can't talk directly to http://localhost:8765 — browsers block mixed-content + cross-origin requests. The tunnel solves it.

There are two paths to choose between:

Path URL Setup time Best for
Quick tunnel Random *.trycloudflare.com URL that changes every session 30 seconds, no account Day-to-day work where you're already running PatchWork live
Named tunnel Permanent subdomain on a domain you own (e.g. glabs.yourdomain.com) ~30 minutes, requires Cloudflare account + a domain on Cloudflare Long-term setups, multi-machine teams, anyone tired of pasting a new URL into PatchWork every session

Start with the quick tunnel. Migrate to a named tunnel once the per-session URL update annoys you enough.

Installing cloudflared

One-time setup. If cloudflared --version already prints a version, skip this section.

Download the latest cloudflared-windows-amd64.exe from the Cloudflare releases page, rename it to cloudflared.exe, and put it somewhere on your PATH (e.g. C:\Windows\System32\ or a folder you add to PATH).

Verify: cloudflared --version

brew install cloudflared

Verify: cloudflared --version

# Debian/Ubuntu
sudo curl -L --output /usr/local/bin/cloudflared \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
sudo chmod +x /usr/local/bin/cloudflared

Verify: cloudflared --version

Path 1: Quick tunnel (per-session)

The fast path. No login, no account, no config file. Each run gets a fresh *.trycloudflare.com URL.

Starting the tunnel

cloudflared tunnel --url http://localhost:8765

You'll see output like:

2026-05-12T17:00:00Z INF Requesting new quick Tunnel on trycloudflare.com...
2026-05-12T17:00:01Z INF +-------------------------------------------------------+
2026-05-12T17:00:01Z INF |  Your quick Tunnel has been created! Visit it at:     |
2026-05-12T17:00:01Z INF |  https://lemon-banana-cabbage-pie.trycloudflare.com   |
2026-05-12T17:00:01Z INF +-------------------------------------------------------+

Copy the printed URL. This is the URL you paste into PatchWork's settings or pass to the Generation Runner via --server.

What the quick tunnel costs you

  • URL changes every session. Restart cloudflared → new random URL → update PatchWork settings + any saved runner config that points at the old one.
  • Can drop after ~30 minutes. Quick tunnels are ephemeral by design. If a long generation pass outlives the tunnel, the run fails partway through and you have to restart with a new tunnel.
  • No control over the URL. You can't bookmark https://my-stuff.example.com because the URL is randomly generated.

For occasional use, none of this matters. For daily work, the named tunnel below avoids all of it.

Path 2: Named tunnel (permanent URL)

The longer-form setup. Requires a Cloudflare account and a domain managed by Cloudflare. Once set up, the URL is permanent — no per-session updates anywhere.

What you need first

  1. A Cloudflare account (free at https://dash.cloudflare.com/sign-up)
  2. A domain managed by Cloudflare — either:
    • A domain you already own, with its nameservers pointed at Cloudflare (free if you already own the domain), OR
    • A domain registered through Cloudflare directly

If you don't have a domain on Cloudflare and don't want to set one up, stick with the quick tunnel — named tunnels without a Cloudflare-managed domain still work but they fall back to a *.trycloudflare.com-style URL, which defeats the point.

Step 1: Authenticate cloudflared with your account

cloudflared tunnel login

This opens a browser window. Sign in to your Cloudflare account, pick the domain you want to use for the tunnel, and authorize. A certificate file gets saved to ~/.cloudflared/cert.pem (Windows: %USERPROFILE%\.cloudflared\cert.pem). You only do this once per machine.

Step 2: Create a named tunnel

Pick a name. Could be anything — glabs, my-glabs, local-backend. The name is for your own bookkeeping.

cloudflared tunnel create glabs

Output:

Tunnel credentials written to /home/you/.cloudflared/abc12345-6789-...-def.json
Created tunnel glabs with id abc12345-6789-...-def

The UUID is the tunnel's permanent identifier. The credentials JSON is what cloudflared uses to authenticate when the tunnel runs. Don't share or commit either.

Step 3: Configure the tunnel's routing

Create (or edit) ~/.cloudflared/config.yml (Windows: %USERPROFILE%\.cloudflared\config.yml):

tunnel: abc12345-6789-...-def   # the UUID from step 2
credentials-file: /home/you/.cloudflared/abc12345-6789-...-def.json

ingress:
  - hostname: glabs.yourdomain.com
    service: http://localhost:8765
  - service: http_status:404

The ingress block tells cloudflared:

  • Requests to glabs.yourdomain.com go to your local http://localhost:8765 (G-Labs)
  • Everything else returns 404

Use whatever subdomain you want (glabs, gen, tunnel, etc.). Replace yourdomain.com with your actual Cloudflare-managed domain.

Step 4: Route DNS to the tunnel

cloudflared tunnel route dns glabs glabs.yourdomain.com

This creates a CNAME record on your Cloudflare DNS that points glabs.yourdomain.com at the tunnel. Cloudflare handles the cert + HTTPS automatically.

Step 5: Run the tunnel

cloudflared tunnel run glabs

The tunnel starts. Verify in a browser: https://glabs.yourdomain.com/health should return G-Labs' 200 OK (assuming G-Labs is running on localhost:8765).

Otherwise you have to remember to run cloudflared tunnel run glabs every session.

cloudflared service install

Installs cloudflared as a Windows service. Auto-starts on boot. Stops with cloudflared service uninstall.

sudo cloudflared service install

Installs as a LaunchAgent. Auto-starts on login.

sudo cloudflared service install

Installs as a systemd service. Enable + start:

sudo systemctl enable cloudflared
sudo systemctl start cloudflared

Using the named tunnel URL

Once running, your G-Labs server URL is permanently https://glabs.yourdomain.com. Paste it into PatchWork's settings ONCE. Use it as --server in the Generation Runner ONCE per saved config. It never changes.

Common issues

"failed to request quick Tunnel" / 530 error
Cloudflare's tunnel service is overloaded or you're being rate-limited. Wait a minute, retry. If persistent, check https://www.cloudflarestatus.com/.
"Origin certificate not found" when creating a named tunnel
You skipped cloudflared tunnel login (Step 1) — there's no cert.pem on disk. Run it.
"Unable to reach the origin service" / 1033 error
Tunnel is up but G-Labs isn't responding at localhost:8765. Hit http://localhost:8765/health directly. If that fails, G-Labs is down or crashed.
Named tunnel URL returns 502
Same diagnosis — G-Labs not running, or config.yml points at the wrong port. Confirm the service: line in config.yml matches G-Labs' actual port.
Quick tunnel drops after 30 minutes mid-generation
Quick tunnels aren't reliable for long-running passes. Either restart cloudflared + update the URL in flight (if the runner supports it), or switch to a named tunnel.
Tunnel URL works for you but not a teammate
Quick tunnels work from anywhere — if a teammate can't reach it, something else is blocking (firewall on their side, geo-block, etc.). Named tunnels run through Cloudflare's CDN and work universally.

Tearing down a named tunnel

If you no longer want a named tunnel:

# stop the service if it's running
cloudflared service uninstall   # or systemctl stop cloudflared

# delete the tunnel
cloudflared tunnel delete glabs

# remove DNS record (in Cloudflare dashboard, or via API)

The DNS CNAME survives tunnel delete — clean it up via the Cloudflare dashboard if you don't want a dangling record.

When you're ready

→ Next: PatchWork Overview — once the tunnel's running and you have a URL, this is where you paste it.