Skip to content

Create a Cloudflared Tunnel

This runbook creates the locally managed homelab tunnel from the Cloudflared CLI and records its ID for later commands.

Prerequisites

  • a Cloudflare account and a domain managed by Cloudflare
  • Cloudflared installed through mise.toml
  • permission to authorize Cloudflared for the domain
  • .env ignored by Git

Authenticate the CLI

cloudflared tunnel login

Open the one-time URL, sign in, and select the domain to authorize. Cloudflared writes the account-level management certificate to ~/.cloudflared/cert.pem. Do not deploy or commit this certificate.

Create the tunnel

Check for an existing tunnel first:

cloudflared tunnel list

Create it only when it does not already exist:

cloudflared tunnel create homelab

Cloudflared writes ~/.cloudflared/<tunnel-id>.json. This file contains the per-tunnel credential and must remain secret.

Record the ID

cloudflared tunnel list -n homelab -o json | jq -r '.[0].id'

Add the result to .env:

CLOUDFLARE_TUNNEL_ID=<tunnel-id>

Verify the tunnel:

cloudflared tunnel info "$CLOUDFLARE_TUNNEL_ID"

The message does not have any active connection is expected until a local or Kubernetes Cloudflared process starts using the credential.

Create the application DNS routes:

cloudflared tunnel route dns "$CLOUDFLARE_TUNNEL_ID" linkding.hyperoot.dev
cloudflared tunnel route dns "$CLOUDFLARE_TUNNEL_ID" postiz.hyperoot.dev

Continue with Store Cloudflared credentials in Vault.

Reference

Cloudflare maintains a list of useful locally managed tunnel commands.