Terminal & SSH

Creating SSH terminals, managing PTY sessions, and terminal features.

Creating a Terminal Session

Click + NEW SESSION in the dashboard or press T to open the session creation modal.

| Mode | When | How | |------|------|-----| | Local | Host is localhost | Spawns local shell via node-pty | | Remote SSH | Any remote host | Runs ssh -t -i keyfile user@host | | tmux attach | Existing session | Runs tmux attach -t 'session' | | tmux new | Wrap in tmux | Runs tmux new-session -s 'name' 'command' |

Configuration Fields

| Field | Default | Notes | |-------|---------|-------| | Host | localhost | From browser URL | | Port | 22 | SSH port | | Username | — | Required for remote | | Auth method | key | key or password | | Private key | — | Listed from ~/.ssh/ | | Working directory | ~ | Supports history dropdown | | Command | claude | claude, codex, or custom | | API key | — | Optional per-session override | | Terminal theme | auto | Matches dashboard theme | | Title | — | Custom display name | | Label | — | Organization label |

Terminal Features

xterm.js Integration

Each terminal runs a full xterm.js instance with:

@xterm/addon-fit — auto-resize to container
@xterm/addon-web-links — clickable URL detection
@xterm/addon-search — text search within terminal

Terminal Themes

8 named themes plus auto:

| Theme | Description | |-------|-------------| | auto | Matches dashboard theme (default) | | dark | Standard dark terminal | | light | White background | | cyberpunk | Magenta/cyan on deep purple | | dracula | Dracula color scheme | | solarized | Solarized dark | | nord | Nord color scheme | | monokai | Monokai colors | | warm | Amber on cream |

Output Buffer

Each terminal maintains a 128KB ring buffer. When a new browser tab connects, the full buffer is replayed so you see previous output without re-running commands.

Fullscreen Mode

Click the fullscreen button or press F11 while the terminal tab is active. Press again to exit.

Shell-Ready Detection

Before sending the launch command, the server waits for the shell prompt to appear:

Buffers PTY output (max 4096 bytes)
Strips ANSI escape sequences
After 100ms of silence, checks if the last line ends with $, #, %, or >
Local timeout: 5 seconds, Remote SSH timeout: 15 seconds

If the timeout expires, the command is sent anyway with a warning log.

Session Linkage

When you create a terminal and launch Claude inside it, the dashboard links the Claude session to the terminal:

Terminal created with AGENT_MANAGER_TERMINAL_ID env var injected
Claude's hook script reads this env var
Hook events include agent_terminal_id field
Server matches the hook to the correct terminal via Priority 1 matching

This allows the detail panel to show both the terminal output and the Claude session data side by side.

Prompt Queue

The Queue tab in the detail panel lets you stage prompts:

Add: Type in the textarea, click Add
Send: Click Send or press Ctrl+Enter to send the first queued item
Reorder: Drag and drop items in the queue
Move: Transfer prompts to a different session
Auto-send: Optional setting to send automatically on terminal focus

Terminal Limits

Maximum 10 terminals can be open simultaneously. Close unused terminals to free slots.

Resume & Reconnect

When a session ends, you can resume it:

Click Resume in the detail panel (or the resume button on the card)
The server creates a new PTY and runs claude --resume {session_id} || claude --continue
The new Claude session links back to the original session data
Previous conversation history appears as collapsible sections