headquarter/openspec/changes/opencode-web-terminal/proposal.md

Why

Tool instances currently have inconsistent port configuration. OpenCode lacks a default port and doesn't expose a web interface, while code-server and jupyter have hardcoded ports. We need a systematic way to define tool ports and ensure OpenCode works properly via the web terminal interface.

What Changes

• Tool Port Configuration: Make default_port required for all tool types and validate it during tool type creation
• OpenCode Web Terminal: Configure OpenCode to run a web server (e.g., on port 3000) so it can be accessed via browser, not just through the raw WebSocket terminal
• Tunnel Port Discovery: Ensure cloudflared tunnels use the correct internal port from the tool type definition
• Terminal-First Tools: Add support for tools that primarily use the terminal interface but may also expose a web UI
• Tool Validation: Add validation to ensure tool compose templates expose the port defined in default_port

Capabilities

New Capabilities

• tool-port-configuration: Systematic port definition and validation for tool types
• opencode-web-server: Running OpenCode with a web interface accessible via browser

Modified Capabilities

• tool-types: Adding port validation requirements and web interface support for terminal tools
• tool-instances: Tunnel creation must read port from tool type configuration
• tool-terminal: Terminal tools may optionally expose web endpoints

Impact

• Backend: Tool type model, validation, seed data, tunnel creation logic
• Frontend: Instance list may show both Open (web) and Terminal buttons for tools with dual interfaces
• Docker: OpenCode compose template needs a web server command
• Infrastructure: Cloudflared tunnels must target the correct internal port