DockFlare Agent & Multi-Server Architecture

DockFlare 3.0 introduces a distributed execution model that lets you manage Cloudflare tunnels across multiple Docker hosts. The DockFlare Master coordinates configuration, while lightweight Agents run alongside your workloads and keep their local cloudflared instance in sync with the master.

This guide explains the architecture, security model, and step-by-step workflow for deploying agents.

Why Agents?

• Decouple compute from ingress – keep workloads close to users while maintaining a single control plane.
• Per-host visibility – monitor heartbeat, tunnel status, and command history for each agent.
• Least-privilege tokens – revoke compromised agents without touching the master or other hosts.
• Resilient updates – agents continue serving traffic with their last-known configuration if the master is temporarily unavailable.

Components at a Glance

The master and Redis typically run together, while agents run next to workloads (potentially on remote networks).

Prerequisites

• DockFlare Master ≥ v3.0 with Redis configured (REDIS_URL set). Optionally specify REDIS_DB_INDEX to isolate data from other containers using the same Redis instance.
• Cloudflare API token with Tunnel + Access permissions (same as previous versions).
• Docker runtime on every host you plan to manage.
• (Optional) Dedicated network segment or VPN between master and agents if you do not expose the master publicly.

Workflow Overview

1. Generate an agent API key in the DockFlare UI (Agents → Generate Key).
2. Deploy the DockFlare Agent container on the remote host, passing the master URL and key.
3. The agent registers with the master and appears with status Pending.
4. From the master UI, enrol the agent – assign or create a Cloudflare tunnel for that host.
5. The master queues commands; the agent polls, applies config, and reports status/heartbeat. DockFlare auto-detects the target zone for each hostname (falling back to the default zone only when detection fails).
6. As containers start/stop on the agent host, the agent streams events back to the master which updates DNS, Access policies, and tunnel ingress rules.

Deploying the DockFlare Agent

The agent is published as alplat/dockflare-agent:latest on Docker Hub.

There are two deployment methods — choose the one that suits your setup:

Option A — One-liner deploy script (recommended, opt-in)

If you have configured Cloudflare Zero Trust on the master (Agents → Setup Zero Trust), DockFlare can generate a fully pre-configured bash script for each agent API key. The script:

• Checks that docker compose is available
• Creates the cloudflare-net Docker network if it does not exist
• Writes a docker-compose.yml with all four required values baked in (DOCKFLARE_MASTER_URL, DOCKFLARE_API_KEY, CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET)
• Starts the agent stack immediately

To use it: go to Agents → (key row) → Deploy Agent → Quick Deploy, copy the script, and paste it into an SSH session on the target server. No .env file setup required.

This option requires the Cloudflare Zero Trust feature to be configured on the master. See the Security Model section for details.

Option B — Manual compose setup

For environments where you manage your own configuration files:

# .env on the agent host
DOCKFLARE_MASTER_URL=https://dockflare.example.com
DOCKFLARE_API_KEY=agent_api_key_goes_here
DOCKER_HOST=tcp://docker-socket-proxy:2375
# Optional: pin the cloudflared image (accepts repo:tag or repo@sha256:<digest>)
# Defaults to cloudflare/cloudflared:latest when not set
CLOUDFLARED_IMAGE=cloudflare/cloudflared:latest
LOG_LEVEL=info
TZ=Europe/Zurich
# Optional: Cloudflare Zero Trust service token (generated by the master)
CF_ACCESS_CLIENT_ID=
CF_ACCESS_CLIENT_SECRET=

Minimal docker-compose.yml on the agent host:

services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.4.1
    container_name: docker-socket-proxy
    restart: unless-stopped
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
      - CONTAINERS=1
      - EVENTS=1
      - NETWORKS=1
      - IMAGES=1
      - POST=1
      - PING=1
      - EXEC=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - dockflare-internal

  dockflare-agent:
    image: alplat/dockflare-agent:latest
    container_name: dockflare-agent
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - DOCKER_HOST=${DOCKER_HOST:-tcp://docker-socket-proxy:2375}
      - TZ=${TZ:-UTC}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    volumes:
      - agent_data:/app/data
    depends_on:
      - docker-socket-proxy
    networks:
      - cloudflare-net
      - dockflare-internal

volumes:
  agent_data:

networks:
  cloudflare-net:
    name: cloudflare-net
    external: true
  dockflare-internal:
    name: dockflare-internal

• Run docker network create cloudflare-net once to provision the shared network used by the master and agents.
• The socket proxy limits the Docker API surface area the agent can reach; only the capabilities set to 1 are exposed.
• The agent image runs as the unprivileged dockflare user (UID/GID 65532). Ensure mounted directories like /app/data are writable by that account.
• Populate a .env file with at minimum DOCKFLARE_MASTER_URL and DOCKFLARE_API_KEY; all other variables are optional overrides.

Security Model

• Master API key – protects the administrative API. The UI only exposes it after you click Show master API key.
• Agent API keys – unique per agent. Revoking a key immediately blocks further registration/commands from that host.
• Cloudflare Zero Trust service tokens (opt-in) – when configured, DockFlare creates a Cloudflare Access Application scoped to /api/v2/agents/ with a non_identity policy. Agents present CF-Access-Client-Id and CF-Access-Client-Secret headers on every request, which Cloudflare validates at the edge before traffic reaches the master. This adds a second authentication layer on top of the agent API key. Admin browser access continues to work through a bypass policy on the same app. Enable it via Agents → Setup Zero Trust.
• Redis – used for queues and caches; secure it (password + network ACLs) if running outside a trusted LAN.
• Transport – run the master behind HTTPS (e.g., via Cloudflare Tunnel) so agent traffic is encrypted in transit.
• Least-privilege runtime – the agent container runs as the dockflare user (UID/GID 65532) and relies on the socket proxy to keep Docker access scoped to container inspection and lifecycle control.

Recommended Hardening

1. Store agent keys in a vault/password manager; rotate regularly.
2. Enable Cloudflare Zero Trust on the master for an additional authentication layer at the Cloudflare edge (Agents → Setup Zero Trust).
3. Do not disable password login - use OAuth/OIDC providers instead for single sign-on convenience without security risks. If you must disable password login, understand that this creates a Docker network security vulnerability where any container on the same network can bypass external authentication. See Accessing the Web UI - Disabling Password Login for full security implications.
4. Use separate tunnels per agent for least-privilege isolation.
5. Monitor Agents page for heartbeat gaps – offline nodes can be removed directly from the UI.

Troubleshooting

Next Steps

• Review the Quick Start in the repository README to ensure Redis is configured.
• Check the changelog for breaking changes and migration notes.
• Consider enabling Cloudflare Zero Trust for hardened agent authentication (Agents → Setup Zero Trust).

Happy tunnelling! 🚇