# 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
