headquarter/openspec/changes/archive/2026-05-22-cloudflare-tunnel-instances-superseded/proposal.md at ba76f09a1cf3aefa10e09bbbf653ca31d8ef8ca8

Files

T

Fusion 2a9e57ad0d chore: archive superseded cloudflare-tunnel-instances OpenSpec change

This change proposed using Cloudflare API for persistent tunnels.
Superseded by temporary tunnel approach using 'cloudflared tunnel --url'
which requires no API tokens, account IDs, or DNS configuration.

2026-05-22 21:01:44 +02:00

2.1 KiB

Raw Blame History

Why

The current approach of proxying tool instances through the backend API is fragile and creates a bottleneck. Every HTTP request and WebSocket connection to a tool instance (code-server, jupyter, etc.) must pass through the FastAPI application, adding latency and consuming API resources. Cloudflare Tunnel provides a robust alternative: each instance gets its own public subdomain with automatic HTTPS, without exposing ports or requiring complex reverse proxy rules.

What Changes

Replace the API proxy endpoint (/instances/{id}/proxy/) with Cloudflare Tunnel integration
Run a cloudflared container alongside the API that manages tunnels programmatically via the Cloudflare API
When a tool instance starts, create a unique Cloudflare Tunnel and DNS record pointing to the instance's internal container name and port
Store the public URL (e.g., https://instance-abc123.headquarter.commumedia.org) in the ToolInstance model
Update the frontend "Open" button to use the Cloudflare URL instead of the proxy path
Remove the proxy endpoint and related code (instance_proxy.py)
BREAKING: The /instances/{id}/proxy/{path:path} endpoint will be removed

Capabilities

New Capabilities

cloudflare-tunnel-management: Creating, deleting, and managing Cloudflare tunnels for tool instances via the Cloudflare API

Modified Capabilities

instance-proxy: The current proxy-based approach will be replaced by Cloudflare tunnels. The requirement that "The API SHALL expose an endpoint that forwards HTTP requests" is replaced by "The system SHALL provide a public URL for each running instance."

Impact

Backend: New Cloudflare tunnel service, updated instance lifecycle (create tunnel on start, delete on stop), removed proxy code
Frontend: Update "Open" links to use public Cloudflare URLs
Infrastructure: New cloudflared Docker service, Cloudflare API token required
Environment: New env vars: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_ZONE_ID
Docker: Cloudflared container must be on the same network as tool instances

2.1 KiB Raw Blame History

Why