cloudflared

cloudflared is the Cloudflare Tunnel connector. It makes an outbound connection to Cloudflare and publishes local HTTP (and some TCP) services on your hostnames with no inbound port open. This sheet covers the CLI, a locally managed config.yml with ingress rules, and Docker Compose.

Documentation: Cloudflare Tunnel · Configuration file Project: cloudflare/cloudflared

Verification: command names, flags and environment variables were read from cloudflared --help output of the cloudflare/cloudflared image (version 2026.10.7), and the example config.yml was accepted by cloudflared tunnel ingress validate and ingress rule. Config keys and the create, route and run flow were checked against the Cloudflare docs. Not verified (no Cloudflare account was used): live tunnel creation, DNS routing, the service install behaviour, the default config and credentials directories on each OS, and the Compose health check. Cloudflare docs also cover the remotely managed (dashboard) tunnels in detail; this sheet covers them only briefly.

See also: Cloudflare · Expose a Service with Cloudflare Tunnel · Docker-Compose · Reverse Proxy Patterns · Tailscale · Traefik

Two Ways to Run a Tunnel #

A tunnel is one or the other: a tunnel created with the dashboard takes its ingress from the dashboard, and config.yml ingress is ignored for it (unverified detail; check the Cloudflare docs).

CLI Commands #

A tunnel can only be deleted with no connections, so stop the connector first. Remove the DNS records made by route dns yourself after deleting a tunnel (unverified).

Useful Options and Variables #

config.yml and Ingress #

Put it at ~/.cloudflared/config.yml, or pass --config. The last ingress rule must be a catch-all, and it must have no hostname.

tunnel: TUNNEL_UUID
credentials-file: /etc/cloudflared/TUNNEL_UUID.json

originRequest:
  connectTimeout: 30s

ingress:
  - hostname: app.example.com
    service: http://app:8080
  - hostname: api.example.com
    path: ^/v1/
    service: http://api:3000
    originRequest:
      noTLSVerify: true
  - hostname: "*.example.com"
    service: http://app:8080
  - service: http_status:404

Docker Compose #

Dashboard-managed (token) tunnel. Keep the token out of the file with a secret file (mode 600, not in git):

services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    restart: unless-stopped
    command: tunnel --no-autoupdate run
    environment:
      TUNNEL_TOKEN_FILE: /run/secrets/tunnel_token
    secrets: [tunnel_token]
    networks: [proxy]

secrets:
  tunnel_token:
    file: ./tunnel-token

networks:
  proxy:
    external: true

Locally managed tunnel with config.yml. Origins are reached by service name on a shared network:

services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    restart: unless-stopped
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yml run
    volumes:
      - ./cloudflared:/etc/cloudflared:ro
    networks: [proxy]

networks:
  proxy:
    external: true

Put config.yml and TUNNEL_UUID.json in ./cloudflared/, with credentials-file: /etc/cloudflared/TUNNEL_UUID.json. Run login and create once on any machine with a browser, then copy the JSON across. cloudflared tunnel ready returns a non-zero exit code when the tunnel is not ready, so it suits a health check (the exact Compose health check was not tested).

Pin the image to a release tag rather than latest, and use --no-autoupdate in containers (Automate Container Updates Safely).

Notes #

• Cloudflare terminates TLS and sees traffic in clear text. Large video streaming over the self-serve plans is restricted (Cloudflare), so Plex or Jellyfin media streams are a poor fit.
• Put Cloudflare Access in front of private apps. A public hostname alone is open to everyone.
• The credentials JSON and run token are secrets: anyone holding them can run your tunnel.

Troubleshooting #

The error codes below come from Cloudflare’s general error pages and were not reproduced (unverified).

See Also #

• Cloudflare
• Expose a Service with Cloudflare Tunnel
• Docker-Compose
• Reverse Proxy Patterns
• Tailscale
• Traefik