headquarter/openspec/changes/cloudflare-tunnel-instances/proposal.md

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