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
105 lines
3.5 KiB
Markdown
105 lines
3.5 KiB
Markdown
# 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:
|
|
1. The terminal shows "Reconnecting..." status
|
|
2. The client automatically attempts to reconnect with exponential backoff
|
|
3. On successful reconnection, buffered output is replayed
|
|
4. You can continue working where you left off
|
|
|
|
## Resetting the Terminal
|
|
|
|
If your terminal becomes unresponsive or you want a fresh start:
|
|
|
|
1. Click the **Reset** button in the terminal header
|
|
2. Confirm the reset action
|
|
3. The current shell is killed and a new one starts
|
|
4. 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 signal
|
|
- `Ctrl+D`: Send EOF (close shell if empty)
|
|
- `Ctrl+L`: Clear screen
|
|
- `Ctrl+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
|