Fusion
40a940304b
- Create enhanced health endpoints with /health and /health/db - Add comprehensive docstrings to all API endpoints - Add Pydantic response models with Field descriptions - Create apps/api/README.md with setup guide - Create ADR-001 for session auth decision - Create ADR-002 for async SQLAlchemy decision - Quality gates: Python syntax OK, TypeScript OK
54 lines
1.8 KiB
Markdown
54 lines
1.8 KiB
Markdown
# Tool Terminal
|
|
|
|
## Problem
|
|
|
|
Tool instances (code-server, jupyter-notebook, etc.) run in Docker containers but users have no way to access a shell inside those containers. This limits debugging, running ad-hoc commands, and managing the container environment.
|
|
|
|
## Solution
|
|
|
|
Provide browser-based terminal access to running tool containers via WebSocket:
|
|
|
|
1. **WebSocket terminal sessions** - Real-time bidirectional communication
|
|
2. **Pseudo-TTY** - Full terminal emulation with proper shell behavior
|
|
3. **xterm.js frontend** - Professional terminal UI in the browser
|
|
4. **Session management** - Multiple independent terminals per instance
|
|
5. **Access control** - Only instance owners can access terminals
|
|
|
|
## Key Features
|
|
|
|
### Terminal Access
|
|
- Open terminal from any running tool instance
|
|
- Full bash/zsh shell inside the container
|
|
- Standard terminal features (colors, cursor, history, etc.)
|
|
|
|
### Real-time I/O
|
|
- Instant character-by-character streaming
|
|
- Stdout/stderr combined output
|
|
- Support for interactive programs (vim, nano, etc.)
|
|
|
|
### Terminal Resize
|
|
- Dynamic column/row adjustment
|
|
- Window resize handled gracefully
|
|
- Proper text wrapping and scrolling
|
|
|
|
### Session Management
|
|
- Multiple terminals per instance
|
|
- Independent sessions with isolation
|
|
- Cleanup on disconnect
|
|
|
|
## Benefits
|
|
|
|
- **Debug containers** - Inspect running processes, check logs
|
|
- **Run commands** - Execute ad-hoc scripts or tools
|
|
- **Manage environment** - Install packages, edit config files
|
|
- **No SSH needed** - Browser-based access from anywhere
|
|
|
|
## Success Criteria
|
|
|
|
- [ ] Terminal opens for any running instance
|
|
- [ ] Commands execute and display output in real-time
|
|
- [ ] Terminal resizes with browser window
|
|
- [ ] Multiple terminals work independently
|
|
- [ ] Sessions clean up on disconnect
|
|
- [ ] Unauthorized users cannot access terminals
|