Files

T

alex 2682e0268c feat: container monitoring integration + polish (PR-3)

- 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

2026-05-29 10:25:00 +02:00

3.5 KiB

Raw Blame History

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 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

3.5 KiB Raw Blame History