Files

T

alex fc873e2d6b docs: add terminal API and user documentation

- Add docs/api/terminal.md with WebSocket protocol and reset endpoint
- Add docs/features/terminal.md with user guide for persistent sessions
- Add docs/features/terminal-troubleshooting.md with diagnostic steps
- Mark tasks 8.1-8.3 complete

Refs: persistent-terminal-sessions tasks 8.x

2026-05-24 12:48:36 +00:00

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

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

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

2.8 KiB Raw Blame History