Cloudflare Tunnel

Cloudflare Tunnel (formerly Argo Tunnel) cree une connexion chiffree, sortante uniquement, de votre instance PRX vers le reseau peripherique de Cloudflare network. Non public IP, open firewall ports, or port forwarding required. Cloudflare terminates TLS and route traffic to your local agent via le tunnel.

Apercu

Cloudflare Tunnel est le recommande backend for production PRX deployments because it provides:

• Zero-trust access -- integrez avec Cloudflare Access pour exiger une verification d'identite before reaching your agent
• Custom domains -- use your own domain avec unutomatic HTTPS certificates
• DDoS protection -- traffic passes through Cloudflare's network, shielding your origin
• High reliability -- Cloudflare maintains multiple edge connections for redundancy
• Free tier -- Cloudflare Tunnels sont disponibles sur le free plan

Prerequis

1. A Cloudflare account (free tier is sufficient)
2. cloudflared CLI installed sur le machine running PRX
3. A domain added to your Cloudflare account (for named tunnels)

Installing cloudflared

# Debian / Ubuntu
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \
  | sudo tee /usr/share/keyrings/cloudflare-main.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] \
  https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install -y cloudflared

# macOS
brew install cloudflared

# Binary download (all platforms)
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

Configuration

Quick Tunnel (Non Domain Requis)

La configuration la plus simple uses Cloudflare's quick tunnel, which assigns a random *.trycloudflare.com subdomain. Non Cloudflare account configuration is needed beyond installing cloudflared:

[tunnel]
backend = "cloudflare"
local_addr = "127.0.0.1:8080"

[tunnel.cloudflare]
# Quick tunnel mode: no token, no named tunnel.
# A random trycloudflare.com URL is assigned on each start.
mode = "quick"

Les tunnels rapides sont ideaux pour le developpement et les tests. L'URL change a chaque redemarrage, donc vous devrez mettre a jour webhook registrations accordingly.

Named Tunnel (Persistent Domain)

For production, use a named tunnel avec un stable hostname:

[tunnel]
backend = "cloudflare"
local_addr = "127.0.0.1:8080"

[tunnel.cloudflare]
mode = "named"

# The tunnel token obtained from `cloudflared tunnel create`.
# Can also be set via CLOUDFLARE_TUNNEL_TOKEN environment variable.
token = "eyJhIjoiNjY..."

# The public hostname that routes to this tunnel.
# Must be configured in the Cloudflare dashboard or via cloudflared CLI.
hostname = "agent.example.com"

Creating a Named Tunnel

# 1. Authenticate cloudflared with your Cloudflare account
cloudflared tunnel login

# 2. Create a named tunnel
cloudflared tunnel create prx-agent
# Output: Created tunnel prx-agent with id <TUNNEL_ID>

# 3. Create a DNS record pointing to the tunnel
cloudflared tunnel route dns prx-agent agent.example.com

# 4. Get the tunnel token (for config.toml)
cloudflared tunnel token prx-agent
# Output: eyJhIjoiNjY...

Configuration Reference

Parameter	Type	Defaut	Description
mode	string	"quick"	"quick" for random URLs, "named" for persistent hostnames
token	string	--	Named tunnel token (required for mode = "named")
hostname	string	--	Public hostname for named tunnel
cloudflared_path	string	"cloudflared"	Path vers le cloudflared binary
protocol	string	"auto"	Transport protocol: "auto", "quic", "http2"
edge_ip_version	string	"auto"	IP version for edge connections: "auto", "4", "6"
retries	integer	5	Number of connection retries before giving up
grace_period_secs	integer	30	Seconds to wait before shutting down active connections
metrics_port	integer	--	Si defini, expose cloudflared metrics on this port
log_level	string	"info"	cloudflared log level: "debug", "info", "warn", "error"

Zero-Trust Access

Cloudflare Access adds an identity layer in front of your tunnel. Users must authenticate (via SSO, email OTP, or service tokens) before reaching your PRX instance.

Setting Up Access Policies

1. Navigate to Cloudflare Zero Trust dashboard
2. Create an Access Application for your tunnel hostname
3. Add an Access Policy avec le desired identity requirements

Cloudflare Access Policy Example:
  Application: agent.example.com
  Rule: Allow
  Include:
    - Email ends with: @yourcompany.com
    - Service Token: prx-webhook-token

Service tokens are useful for automated webhook senders (GitHub, Slack) that ne peut pas perform interactive authentication. Configure le token in your webhook fournisseur's headers:

CF-Access-Client-Id: <client-id>
CF-Access-Client-Secret: <client-secret>

Health Checks

PRX surveille the Cloudflare Tunnel health by:

1. Checking that the cloudflared processus enfant is running
2. Sending an HTTP GET vers le public URL and verifying a 2xx response
3. Parsing cloudflared metrics (if metrics_port is configured) for connection status

Si le tunnel becomes unhealthy, PRX logs a warning and attempts to restart cloudflared. The restart follows an exponential backoff strategy: 5s, 10s, 20s, 40s, jusqu'a a maximum of 5 minutes between attempts.

Logs and Debugging

cloudflared stdout and stderr sont captures by TunnelProcess and written vers le PRX log at DEBUG level. To increase verbosity:

[tunnel.cloudflare]
log_level = "debug"

Common log messages and their meanings:

Log Message	Meaning
Connection registered	Tunnel established to Cloudflare edge
Retrying connection	Edge connection dropped, attempting reconnect
Serve tunnel error	Fatal error, tunnel will restart
Registered DNS record	DNS route successfully created

Exemple: Full Production Setup

[tunnel]
backend = "cloudflare"
local_addr = "127.0.0.1:8080"
health_check_interval_secs = 30
max_failures = 3

[tunnel.cloudflare]
mode = "named"
token = "${CLOUDFLARE_TUNNEL_TOKEN}"
hostname = "agent.mycompany.com"
protocol = "quic"
retries = 5
grace_period_secs = 30
log_level = "info"

# Set the token via environment variable
export CLOUDFLARE_TUNNEL_TOKEN="eyJhIjoiNjY..."

# Start PRX -- tunnel starts automatically
prx start

Securite Nontes

• The tunnel token grants full access vers le named tunnel. Store it in the PRX secrets manager or pass it via variable d'environnement. Never commit it to version control.
• Quick tunnels ne faites pas support Access policies. Use named tunnels for production.
• cloudflared runs comme un processus enfant avec les memes user permissions as PRX. Consider running PRX under a dedicated service account with minimal privileges.
• All traffic between cloudflared et Cloudflare's edge is encrypted with TLS 1.3 ou QUIC.

Voir aussi Pages

• Tunnel Overview
• Tailscale Funnel
• ngrok
• Security Overview
• Secrets Management