headquarter/openspec/changes/instance-proxy/proposal.md at 8dd350286e034de5ca3f65b33b633ad4972dd37c

Files

T

Fusion 74b5d0dc8c feat(instance-proxy): add HTTP proxy for tool instances

Add API proxy endpoint so users can access running tool instances
through the backend API instead of internal Docker network.

Backend:
- Add container_name field to ToolInstance model
- Create /instances/{id}/proxy/{path:path} endpoint with ownership checks
- Proxy HTTP requests to containers via docker network using container names
- Support all HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
- Store proxy URL in instance.url instead of localhost
- Add Alembic migration 0007 for container_name column
- Add get_container_name() utility to docker.py

Frontend:
- Update Open button to use full proxy URL (API_BASE_URL + instance.url)

Closes instance-proxy OpenSpec change.

2026-05-20 10:37:21 +02:00

1.3 KiB

Raw Blame History

Why

Tool instances (code-server, jupyter-notebook) run inside Docker containers with internal network addresses. Currently the "Open" button links to http://localhost:{port}, which only works from inside the API container and fails when opened from the user's browser. We need a way to expose these instances to users over HTTPS.

What Changes

Add a proxy endpoint to the backend API: /instances/{id}/proxy/{path:path}
Proxy requests from the API to the running container (via docker network or internal IP)
Update frontend "Open" button to use the proxy URL instead of localhost
Add WebSocket proxy support for real-time features (terminal already uses WebSocket)
Ensure only the instance owner can access the proxied content

Capabilities

New Capabilities

instance-proxy: HTTP proxying for running tool instances through the API

Modified Capabilities

None (this is purely an infrastructure/transport feature, not a change to existing capability requirements)

Impact

Backend: New proxy endpoint, container network discovery, request forwarding
Frontend: Update instance "Open" link to use proxy URL
Docker: Containers must be reachable from API container (already true via docker network)
Security: Owner-only access enforced at proxy level

1.3 KiB Raw Blame History

Why