cloudflare-tunnels

Cloudflare Tunnels

Cloudflare Tunnels create encrypted, outbound-only connections from your infrastructure to Cloudflare's network. No public IP, open ports, or firewall rules needed — the cloudflared daemon runs on your server and reaches out to Cloudflare.

• Docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
• Dashboard: https://dash.cloudflare.com/?to=/:account/networks/tunnels
• CLI: cloudflared (brew install cloudflared)
• Pulumi resources: cloudflare.ZeroTrustTunnelCloudflared, cloudflare.ZeroTrustTunnelCloudflaredConfig
• Docker image: cloudflare/cloudflared (Docker Hub)

Architecture

Internet → Cloudflare Edge → Tunnel (encrypted) → cloudflared → Your Services
                  ↓
         Access Policies (optional)
         WAF / DDoS Protection
         SSL Termination

The tunnel is outbound-only — your server connects to Cloudflare, not the other way around. This means:

• No need for a public IP address
• No inbound firewall rules required
• No port forwarding on your router
• Works behind NAT, CGNAT, or corporate firewalls

Authentication Methods

Token-based (Recommended for automation)

Create a tunnel in the Cloudflare dashboard or via API, then use the generated token:

cloudflared tunnel --no-autoupdate run --token <TUNNEL_TOKEN>

Credentials file (Legacy)

cloudflared tunnel login          # Interactive browser auth
cloudflared tunnel create my-tunnel
cloudflared tunnel run my-tunnel  # Uses ~/.cloudflared/<tunnel-id>.json

Configuration File

# ~/.cloudflared/config.yml
tunnel: <TUNNEL_UUID>
credentials-file: /path/to/credentials.json

ingress:
  - hostname: app.example.com
    service: http://localhost:8080
  - hostname: api.example.com
    service: http://localhost:3000
    originRequest:
      noTLSVerify: true # Skip TLS verification to origin
      connectTimeout: 30s
  - hostname: ssh.example.com
    service: ssh://localhost:22
  - hostname: rdp.example.com
    service: rdp://localhost:3389
  - service: http_status:404 # Catch-all (REQUIRED — must be last)

Ingress Service Types

Protocol	Example	Use Case
http://host:port	Web apps, APIs	Most common
https://host:port	TLS-terminated origins	When origin has its own cert
ssh://host:port	SSH access	Remote shell via browser
rdp://host:port	Remote Desktop	Windows RDP via browser
tcp://host:port	Raw TCP	Databases, custom protocols
unix:/path/to/socket	Unix sockets	Docker socket, etc.
http_status:404	Static response	Catch-all fallback

Docker Compose Deployment

Basic Setup

# docker-compose.yaml
name: cloudflared

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: always
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
    networks:
      - cloudflared

networks:
  cloudflared:
    driver: bridge
    name: cloudflared

Production Setup with 1Password Secrets

For production deployments, avoid putting tokens in environment variables. Use an init container to fetch secrets from a secrets manager:

# docker-compose.yaml
name: cloudflared

services:
  init-secrets:
    image: 1password/op:2
    user: "0:0"
    environment:
      - OP_SERVICE_ACCOUNT_TOKEN=${OP_SERVICE_ACCOUNT_TOKEN}
    volumes:
      - cloudflare-secrets:/run/secrets:rw
    command:
      - /bin/bash
      - -c
      - |
        op read "op://Infrastructure/cloudflared/token" > /run/secrets/cloudflared_token
        chmod 444 /run/secrets/*

  cloudflared:
    image: cloudflare/cloudflared:2026.3.0 # Pin version for reproducibility
    restart: always
    command: tunnel --no-autoupdate run --token-file /run/secrets/cloudflared_token
    volumes:
      - cloudflare-secrets:/run/secrets:ro
    depends_on:
      init-secrets:
        condition: service_completed_successfully
    networks:
      - cloudflared

volumes:
  cloudflare-secrets:
    driver: local

networks:
  cloudflared:
    driver: bridge
    name: cloudflared

Connecting Other Services

Other docker-compose stacks join the cloudflared network to be reachable via the tunnel:

# In another stack's docker-compose.yaml
services:
  my-app:
    image: my-app:latest
    networks:
      - cloudflared

networks:
  cloudflared:
    external: true # Join the network created by the cloudflared stack

Then add the hostname → service mapping in the Cloudflare dashboard (or via Pulumi/API).

GitOps with Arcane

If using Arcane for GitOps deployment of docker-compose stacks, place the cloudflared compose file in your iac repo at hosts/<hostname>/cloudflared/docker-compose.yaml. Arcane will sync and deploy it automatically on push to main. See the arcane plugin's arcane-gitops skill for the full GitOps workflow.

Directory structure:

iac/
  hosts/
    my-server/
      cloudflared/
        docker-compose.yaml
      my-app/
        docker-compose.yaml   # Joins cloudflared network

Proxmox LXC Deployment

For running cloudflared in a Proxmox LXC container (lightweight alternative to a full VM):

Option 1: Direct Install in LXC

# On the Proxmox host, create an unprivileged LXC container
pct create 200 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname cloudflared \
  --memory 512 \
  --cores 1 \
  --rootfs local-lvm:4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --unprivileged 1

pct start 200

# Inside the LXC container
pct enter 200
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared bookworm main" \
  | tee /etc/apt/sources.list.d/cloudflared.list
apt update && apt install -y cloudflared

# Run as a service
cloudflared service install <TUNNEL_TOKEN>
systemctl enable --now cloudflared

Option 2: Docker in LXC (for docker-compose stacks)

For running docker-compose stacks (including cloudflared) in an LXC container, you need a privileged container with nesting enabled. See the proxmox plugin's proxmox-lxc skill for detailed setup instructions.

# Create privileged LXC with nesting for Docker support
pct create 201 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname docker-host \
  --memory 2048 \
  --cores 2 \
  --rootfs local-lvm:20 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --features nesting=1 \
  --unprivileged 0

pct start 201

# Inside the LXC, install Docker
pct enter 201
curl -fsSL https://get.docker.com | sh

# Then deploy cloudflared via docker-compose as shown above

Pulumi IaC

Create a Tunnel

import * as pulumi from "@pulumi/pulumi";
import * as cloudflare from "@pulumi/cloudflare";

const config = new pulumi.Config();
const cfConfig = new pulumi.Config("cloudflare");
const accountId = cfConfig.require("accountId");

// Generate a tunnel secret (32+ bytes, base64-encoded)
const tunnelSecret = config.requireSecret("tunnelSecret");

const tunnel = new cloudflare.ZeroTrustTunnelCloudflared("my-tunnel", {
  accountId,
  name: "my-tunnel",
  secret: tunnelSecret,
});

// Export the token for use with cloudflared
export const tunnelToken = tunnel.tunnelToken;

Configure Ingress Rules

const tunnelConfig = new cloudflare.ZeroTrustTunnelCloudflaredConfig("my-tunnel-config", {
  accountId,
  tunnelId: tunnel.id,
  config: {
    ingressRules: [
      {
        hostname: "app.example.com",
        service: "http://my-app:8080",
      },
      {
        hostname: "api.example.com",
        service: "http://my-api:3000",
        originRequest: {
          connectTimeout: "30s",
          noTlsVerify: true,
        },
      },
      {
        // Catch-all (required, must be last)
        service: "http_status:404",
      },
    ],
  },
});

DNS Records for Tunnel

const zone = cloudflare.getZoneOutput({ name: "example.com", accountId });

const appDns = new cloudflare.Record("app-dns", {
  zoneId: zone.id,
  name: "app",
  type: "CNAME",
  content: pulumi.interpolate`${tunnel.id}.cfargotunnel.com`,
  proxied: true,
});

const apiDns = new cloudflare.Record("api-dns", {
  zoneId: zone.id,
  name: "api",
  type: "CNAME",
  content: pulumi.interpolate`${tunnel.id}.cfargotunnel.com`,
  proxied: true,
});

Combine with Access Policies

Protect tunnel-exposed services with Zero Trust Access (see the cloudflare-zero-trust skill):

const accessApp = new cloudflare.ZeroTrustAccessApplication("app-access", {
  zoneId: zone.id,
  name: "Internal App",
  domain: "app.example.com",
  type: "self_hosted",
  sessionDuration: "24h",
});

const accessPolicy = new cloudflare.ZeroTrustAccessPolicy("allow-team", {
  applicationId: accessApp.id,
  zoneId: zone.id,
  name: "Allow Team",
  precedence: 1,
  decision: "allow",
  includes: [
    {
      emails: ["admin@example.com"],
    },
  ],
});

Monitoring

# Check tunnel status
cloudflared tunnel info my-tunnel

# View tunnel metrics (Prometheus format)
cloudflared tunnel --metrics localhost:2000

# Dashboard: see active connections, latency, errors
# https://dash.cloudflare.com/?to=/:account/networks/tunnels

Troubleshooting

Issue	Solution
Tunnel won't connect	Check TUNNEL_TOKEN / credentials file. Verify DNS resolves
ERR_CONNECTION_REFUSED	Origin service isn't running or wrong port
Intermittent 502s	Increase connectTimeout in ingress config
Can't reach service from tunnel	Ensure both containers are on the same Docker network
Token file permission denied	Check volume mount permissions (:ro vs :rw)
LXC DNS issues	Add --nameserver 1.1.1.1 to LXC config

References

• Tunnels Docs
• Create a Tunnel (Dashboard)
• Tunnel Configuration
• Ingress Rules
• cloudflared Downloads
• Docker Hub: cloudflare/cloudflared
• Pulumi ZeroTrustTunnelCloudflared
• Pulumi ZeroTrustTunnelCloudflaredConfig