zero-tunnel

zero-tunnel

zero-tunnel is an automation tool that dynamically manages Cloudflare Tunnel routes based on Docker container labels. It automatically updates tunnel ingress rules and DNS CNAME records when containers start or stop.

For a detailed technical specification, see SPECS.md.

Table of Contents

• zero-tunnel
  • Table of Contents
  • Features
  • How It Works
  • Prerequisites
  • Configuration
    • Environment Variables
    • Docker Labels
    • Path Matching
  • Getting Started
    • Docker Compose (Recommended)
    • Other Installation Methods
      • Build from Source
      • Nix
  • Development
  • License

Features

• Automated Routing – Expose Docker services via Cloudflare Tunnels using simple container labels.
• DNS Management – Automatically creates and removes CNAME records tagged with managed-by:zero-tunnel.
• Real-time Sync – Updates Cloudflare configuration immediately when containers start or stop.
• Debounced Updates – Batches rapid events (e.g., during docker compose up) to respect API rate limits.
• Periodic Reconciliation – Detects and corrects drift between desired state and actual Cloudflare configuration.

How It Works

zero-tunnel continuously bridges your Docker environment and Cloudflare Tunnel configuration:

1. Startup – Scans all running containers, builds an initial routing map, and syncs ingress rules and DNS records with Cloudflare.
2. Event loop – Watches Docker events (start, stop, die, destroy). On start, adds or updates the route. On stop/die, removes it.
3. Reconciliation – Runs on a configurable interval to clean up orphaned DNS records and fix any configuration drift caused by external changes.

[!IMPORTANT] zero-tunnel manages routing configuration only. cloudflared and your target containers must share the same Docker network (or otherwise have direct IP connectivity) so that cloudflared can reach them by container name and port.

Prerequisites

• Docker – Access to the Docker socket (usually /var/run/docker.sock).
• Cloudflare Account with:
  • A Remotely Managed Tunnel created via the Zero Trust Dashboard.
  • An API Token with the following permissions:
    • Account / Cloudflare Tunnel: Edit
    • Account / Account Settings: Read
    • Zone / DNS: Edit
    • Zone / Zone: Read

Configuration

Environment Variables

⚠️ Either CLOUDFLARE_TUNNEL_ID or CLOUDFLARE_TUNNEL_NAME must be set, but not both.

Docker Labels

Apply these labels to any container you want to expose.

Path Matching

The zero-tunnel.path label uses Cloudflare Tunnel ingress regex syntax:

Getting Started

Docker Compose (Recommended)

Download the example files:

wget https://raw.githubusercontent.com/aspiand/zero-tunnel/main/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/aspiand/zero-tunnel/main/.env.example

Edit .env with your Cloudflare credentials, then start everything:

docker compose up -d

Other Installation Methods

Build from Source

Requires Go to be installed.

# Build
go build

# Run (ensure environment variables are set)
./zero-tunnel

Nix

Requires Nix with flakes enabled.

nix run github:aspiand/zero-tunnel

Development

For local development with hot reload, install air and run:

air

License

This project is licensed under the MIT License – see the LICENSE file for details.