alex
2682e0268c
- Integration tests: SSE auth, connection limits, lifecycle hooks, event persistence (6 tests)
- Instance events history API: GET /instances/{id}/events
- Documentation updates: terminal.md, backend.md, frontend.md
- Performance: SSE max 5 connections, health monitor write-on-change
Quality gates: pytest 21 monitoring passed, 172 unit passed (4 pre-existing), vitest 14 passed, tsc clean, eslint clean, ruff clean
3.5 KiB
Terminal Sessions
Terminal sessions provide interactive shell access to your running tool instances directly in the browser.
Persistent Sessions
Terminal sessions are persistent - they survive browser refreshes, network interruptions, and tab switches.
How It Works
- When you open a terminal, a shell session starts inside the tool instance container
- If you close the browser or lose connection, the session keeps running
- When you reconnect, you reattach to the same session with all previous output preserved
- Sessions automatically clean up after 30 minutes of inactivity
Reconnecting
If your connection drops:
- The terminal shows "Reconnecting..." status
- The client automatically attempts to reconnect with exponential backoff
- On successful reconnection, buffered output is replayed
- You can continue working where you left off
Resetting the Terminal
If your terminal becomes unresponsive or you want a fresh start:
- Click the Reset button in the terminal header
- Confirm the reset action
- The current shell is killed and a new one starts
- All terminal history is cleared
Note: Resetting only affects the terminal session, not the tool instance itself. Any files you've created remain intact.
Mobile Terminal
On mobile devices, the terminal includes:
- Special keys panel (Ctrl, Alt, Tab, arrows, etc.)
- Font size controls
- Auto-hiding header for maximum screen space
- Touch-friendly interface
Keyboard Shortcuts
Standard terminal shortcuts work as expected:
Ctrl+C: Send interrupt signalCtrl+D: Send EOF (close shell if empty)Ctrl+L: Clear screenCtrl+Z: Suspend process
Special keys can be accessed via the special keys panel on mobile or by using modifier combinations.
Container Monitoring & Notifications
The platform monitors your tool instances in real-time and notifies you of important events:
What You'll See
- Starting: When a container begins starting
- Running: When a container is ready
- Error: When a build fails, container crashes, or tunnel fails
- Stopped: When a container stops
Notifications appear as toast messages at the top of the screen. Errors persist until dismissed; other notifications auto-dismiss after a few seconds.
Real-Time Status
Instance status badges update in real-time via Server-Sent Events (SSE) — no page refresh needed.
Troubleshooting
Connection Issues
"Connection closed" error:
- The tool instance may have stopped - check the instance status
- Network issues - the client will auto-reconnect
- Session timeout - sessions expire after 30 minutes of inactivity
"Container not found" error (4004):
- The Docker container no longer exists (e.g., after host restart)
- Restart the tool instance to recreate the container
Terminal not responding:
- Try resetting the terminal using the Reset button
- Check if the tool instance is still running
- Refresh the page to force reconnection
Display Issues
Text not visible:
- Adjust font size using +/- buttons
- Check if the terminal has focus (click inside it)
- Try resizing the browser window
Characters not appearing:
- Ensure the terminal has focus
- Check if a modifier key is stuck (Ctrl, Alt)
- Reset the terminal if stuck
Session Limits
- One connection per terminal: Only one browser tab can connect to a terminal session at a time. Opening a new connection closes the old one.
- 30-minute idle timeout: Sessions without activity are automatically cleaned up
- Buffer size: Up to 10KB of output is buffered for replay on reconnection