nsheaps/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: ["[email protected]"],
    },
  ],
});

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