Feature Request: Decouple Cloudflare Tunnel agent from Dockflare controller via HTTP API(or some way)

[ChanningHe]

I’d like to propose a feature that allows the Dockflare controller to run separately from the Cloudflare Tunnel agent, with communication over a defined HTTP API (Not just mount Docker socket over TCP).

Why this matters
In my environment, any service exposed to the public internet is treated as a high-risk zone and is placed in a dedicated VLAN for isolation.
The Dockflare controller currently has access to both:

• Cloudflare API keys with high privileges
• The Docker socket, which effectively provides root-level control even in ro mode.

If the host running public-facing services is compromised, the attacker could leverage Dockflare’s access to gain control over Cloudflare tunnels or DNS records, creating a significant security risk.

By separating the control plane (Dockflare controller) from the public service plane (Cloudflare Tunnel agent), we could deploy Dockflare in a secure management VLAN while running the tunnel agent in the exposed VLAN, significantly reducing the blast radius of any potential compromise.

[ChrispyBacon-dev]

Hey,

Good question. You're thinking about this the right way.

You're right, pretty much everything DockFlare does is just making API calls to Cloudflare. All the ingress rules and DNS stuff can be managed from anywhere. And you can definitely monitor Docker events remotely over a TCP socket, so the main part of DockFlare doesn't need to be on the same machine at all.

The one tricky part, and the reason a small local piece would still be needed, is the cloudflared container itself. It needs that secret tunnel token to start up. The main DockFlare app gets the token from Cloudflare's API, but something on the actual host needs to grab it and pass it to the cloudflared process.

This leads directly to the architecture you're getting at. It would be a two-part system. You'd have the main "Controller" app running somewhere safe with all the API keys, watching Docker remotely. Then you'd have a new, tiny "Agent" on the public host. It would have no permissions at all. Its only job would be to ask the Controller for the tunnel token and then start the cloudflared container with it.

That way, if the public host gets compromised, the attacker gets nothing important. It's the right way to build this for more secure setups.

It's a big change from how things work now, so it's a long-term goal. But I'm officially putting it on the project roadmap. Thanks for helping think through the details on this, it's really helpful.

Cheers,
Chris

[ChanningHe]

Thanks for the thoughtful response!

I think the risk of exposing a single cf tunnel token on the agent side is acceptable—the worst case is losing control of that one public-facing tunnel, which isn’t too critical.

I get that a full controller/agent split is a big architectural change. I’ve opened a PR to support TCP sockets, so we can at least isolate Dockflare and the agent into different VLANs. It’s not perfect, but it’s a step toward better separation.

[ChrispyBacon-dev]

This feature is currently under heavy development and I had some successful tests today. API key from master DockFlare instance is working, the DockFlare Agent can communicate via API to master. 🥳

Architecture & Communication Flow DockFlare & DockFlare Agent in multi server mode

sequenceDiagram
    participant User
    participant Agent as DockFlare Agent
    participant Master as DockFlare Master
    participant Cloudflare

    User->>Agent: Deploys Agent with MASTER_URL and API_KEY
    Agent->>Master: 1. Register (I'm alive, here is my key!)
    Master-->>Agent: 2. Acknowledged (Key is valid. Waiting for enrollment)

    User->>Master: Accesses "Agents" UI, sees new pending Agent
    User->>Master: 3. Enrolls Agent (assigns it a Tunnel Name)
    Master->>Agent: 4. Configuration Command (Start Tunnel 'T1')

    Agent->>Cloudflare: 5. Starts & Manages cloudflared process for Tunnel 'T1'
    Agent->>Master: 6. Status Update (Tunnel is running)

    loop Docker Event Monitoring
        Agent->>Agent: Detects new container with labels
        Agent->>Master: 7. Reports new container event
        Master->>Cloudflare: 8. Creates DNS Record via API
        Master->>Cloudflare: 9. Creates/Updates CF Access Policy via API
    end

Loading

very small preview :