Cloudflare Tunnel Setup Skill

Interactive guide for setting up a new Cloudflare Tunnel from scratch.

Quick Start

Run this skill when you need to:

1. Create a new Cloudflare Tunnel
2. Replace an expired or invalid tunnel token
3. Set up remote access for a fresh installation

Minimum requirements: Cloudflare account, domain on Cloudflare, Docker installed.

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Check Prerequisites
   • 3.2 Create Tunnel in Dashboard
   • 3.3 Configure Token in .env
   • 3.4 Restart Cloudflared Container
   • 3.5 Configure Public Hostnames
   • 3.6 Verify Connectivity
4. Supporting Files
5. Expected Outcomes
6. Requirements
7. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• "Setup cloudflare tunnel"
• "Create a new tunnel"
• "Configure remote access"
• "Replace tunnel token"
• "Tunnel from scratch"

Implicit Triggers:

• Fresh installation of network infrastructure
• Tunnel token expired or invalid
• CLOUDFLARE_TUNNEL_TOKEN missing from .env
• Moving infrastructure to new hardware

Debugging Triggers:

• "Tunnel token not found"
• "cloudflared container won't start"
• "No CLOUDFLARE_TUNNEL_TOKEN in .env"

What This Skill Does

1. Checks Prerequisites - Verifies .env exists and cloudflared is in docker-compose
2. Guides Tunnel Creation - Step-by-step instructions for Cloudflare dashboard
3. Configures Token - Adds tunnel token to .env file
4. Restarts Container - Restarts cloudflared to apply new token
5. Guides Hostname Setup - Instructions for configuring public hostnames
6. Verifies Connectivity - Confirms tunnel is connected and working

Instructions

3.1 Check Prerequisites

Step 1: Verify .env file exists

ls -la /home/dawiddutoit/projects/network/.env

If missing, create from example:

cp /home/dawiddutoit/projects/network/.env.example /home/dawiddutoit/projects/network/.env

Step 2: Check if CLOUDFLARE_TUNNEL_TOKEN exists

grep -E "^CLOUDFLARE_TUNNEL_TOKEN" /home/dawiddutoit/projects/network/.env

Possible outcomes:

• Line exists with value: Token already configured (check if valid)
• Line exists but empty/placeholder: Needs real token
• Line not found: Token needs to be added

Step 3: Verify docker-compose has cloudflared service

grep -A 10 "cloudflared:" /home/dawiddutoit/projects/network/docker-compose.yml

If cloudflared service is missing, it needs to be added. See references/reference.md for service definition.

3.2 Create Tunnel in Dashboard

Provide these instructions to the user:

1. Go to: https://one.dash.cloudflare.com -> Access -> Tunnels
2. Click "Create a tunnel" -> Select "Cloudflared" connector
3. Name tunnel (e.g., "pi-home") -> Choose "Docker" as connector type
4. Copy the tunnel token (long base64 string after --token)
5. Save token securely

Token format: Base64-encoded JSON containing Account ID, Tunnel ID, and Secret.

3.3 Configure Token in .env

Step 1: Check current token status

grep "CLOUDFLARE_TUNNEL_TOKEN" /home/dawiddutoit/projects/network/.env

Step 2: Add or update token

If line exists, update it. If not, add it.

# If line exists, use sed to replace
# If not, append to file

# The token should look like:
# CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjZDEyMzQ...

Use the Edit tool to update .env:

• Look for existing CLOUDFLARE_TUNNEL_TOKEN= line
• Replace with new token value
• Or add new line if not present

Validate token format:

# Token should be base64 decodable
TUNNEL_TOKEN=$(grep "CLOUDFLARE_TUNNEL_TOKEN=" /home/dawiddutoit/projects/network/.env | cut -d'=' -f2)
echo "$TUNNEL_TOKEN" | base64 -d 2>/dev/null | python3 -c "import sys, json; d=json.load(sys.stdin); print('Valid token for account:', d.get('a', 'unknown'))"

3.4 Restart Cloudflared Container

Step 1: Restart the container

cd /home/dawiddutoit/projects/network && docker compose restart cloudflared

Or if container doesn't exist yet:

cd /home/dawiddutoit/projects/network && docker compose up -d cloudflared

Step 2: Check container is running

docker ps | grep cloudflared

Expected output:

CONTAINER ID   IMAGE                         STATUS         NAMES
abc123...      cloudflare/cloudflared:latest Up X seconds   cloudflared

Step 3: Check logs for successful connection

docker logs cloudflared --tail 30

Look for these success indicators:

INF Registered tunnel connection connIndex=0 location=...
INF Registered tunnel connection connIndex=1 location=...
INF Registered tunnel connection connIndex=2 location=...
INF Registered tunnel connection connIndex=3 location=...

4 registered connections = healthy tunnel (2 connections per Cloudflare edge location)

If errors appear:

• token is invalid: Token was copied incorrectly or expired
• already registered: Another instance using same token (stop other instances)
• network error: Check internet connectivity

3.5 Configure Public Hostnames

After tunnel is connected, configure services in Cloudflare dashboard:

1. Go to: https://one.dash.cloudflare.com -> Access -> Tunnels
2. Click tunnel name -> Configure -> Public Hostname -> Add
3. For each service, enter subdomain, domain (temet.ai), Type (HTTP), and URL

Example hostnames:

URL patterns:

• Docker container: container:port (e.g., pihole:80)
• Host service: host-ip:port (e.g., 192.168.68.135:16686)
• LAN device: device-ip:port (e.g., 192.168.68.105:80)

Important: Use HTTP (not HTTPS) for backends. Do NOT use host.docker.internal on Linux.

3.6 Verify Connectivity

Step 1: Verify tunnel is registered

docker logs cloudflared 2>&1 | grep -E "Registered tunnel|connIndex"

Expected: 4 "Registered tunnel connection" messages

Step 2: Check tunnel status in dashboard

Go to: https://one.dash.cloudflare.com
Navigate to: Access -> Tunnels
Status should show: "HEALTHY" with green indicator

Step 3: Test external access (from mobile data or external network)

# From a device NOT on home network:
curl -I https://pihole.temet.ai

# Expected: HTTP 302 (redirect to Cloudflare Access) or HTTP 200 (if no auth)

Step 4: Run diagnostic script (optional)

./scripts/cf-tunnel-config.sh show

Supporting Files

Expected Outcomes

Success:

• CLOUDFLARE_TUNNEL_TOKEN in .env
• cloudflared container running
• 4 tunnel connections registered in logs
• Tunnel shows "HEALTHY" in dashboard
• Services accessible via *.temet.ai from external network

Partial Success:

• Token configured but hostnames not set up (user reminder provided)
• Tunnel connected but services return 502 (backend configuration issue)

Failure Indicators:

• "token is invalid" in logs -> Re-copy token from dashboard
• Container restart loop -> Check token format
• 0 registered connections -> Network/firewall issue

Requirements

Environment:

• Cloudflare account with domain
• Docker and Docker Compose installed
• Internet connectivity
• .env file in project root

Accounts/Access:

• Cloudflare dashboard access
• Zero Trust enabled (free tier works)

Tools needed:

• Read, Write, Edit (for .env configuration)
• Bash (for docker commands and verification)
• Grep (for checking existing configuration)

Red Flags to Avoid

• Do not commit tunnel token to git (keep in .env only)
• Do not use host.docker.internal on Linux hosts
• Do not use HTTPS URLs for internal service backends
• Do not share tunnel tokens between environments
• Do not skip the verification step (3.6)
• Do not forget to configure public hostnames after tunnel connects
• Do not leave placeholder token values in .env

Notes

• Tunnel tokens do not expire but can be revoked in dashboard
• Each tunnel can have multiple connectors (for redundancy)
• Tunnel configuration changes apply automatically (no restart needed)
• Use ./scripts/cf-tunnel-config.sh configure to update ingress via API
• For authentication, use the configure-google-oauth skill after tunnel setup
• The existing troubleshoot-tunnel-connectivity skill handles issues with running tunnels