headquarter/openspec/changes/archive/2026-05-22-instance-proxy/proposal.md at efe5e4ae50df7b76b46d9341e699fc8e32d3c058

Files

T

Fusion 063a839790 feat: implement repository clone mode with SSH key support

- Add clone_mode and branch fields to tool_instances
- Add ssh_key_id to git_repositories for per-repo SSH key assignment
- Implement host-side git cloning with branch selection (default: main)
- Mount SSH keys into containers for git operations in clone mode
- Add dirty state check on clone-mode instance deletion with confirmation
- Update SessionsPage with mount/clone selector, branch input, SSH key display
- Add SSH key selector to repository creation form
- Add dirty delete confirmation modal with changed files list
- Update API schemas and endpoints for new fields
- Sync delta specs to main specs (git-repo, tool-instances, repo-clone-mode)
- Archive completed OpenSpec change: repo-clone-mode-with-ssh
- Document git requirement for custom tool types

Quality gates: Frontend typecheck and build passed
OpenSpec: repo-clone-mode-with-ssh archived with all tasks complete

2026-05-22 22:56:35 +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