Terminal
The terminal provides interactive shell access inside a running preview container via xterm.js.
Requirements#
- An active preview container must be running for the project
project:settingspermission required — by default, only Admin and Owner roles have this permission
Accessing the Terminal#
Open the terminal from the bottom panel of the Command Center. If a preview is running, the terminal connects automatically.
Features#
- Full terminal emulation — xterm.js provides complete terminal behavior including keyboard shortcuts, cursor movement, and control sequences
- Base64 I/O — All input and output is transmitted as base64 over WebSocket for binary safety
- Auto-reconnection — Transparent reconnection if the WebSocket connection drops
- Auto-resize — Terminal adapts to panel and window size changes
- Sandbox isolation — Commands run inside the Docker container, isolated from the host system
Session Tracking#
Terminal sessions are recorded in the database for audit purposes:
- Who opened the session (user ID)
- When the session started and ended
- Which project the session was for
Session records are visible to workspace admins.
WebSocket Protocol#
The terminal WebSocket supports these message types:
| Type | Direction | Description |
|---|---|---|
input | Client → Server | Terminal input (base64-encoded) |
output | Server → Client | Terminal output (base64-encoded) |
resize | Client → Server | Terminal dimensions (cols, rows) |
status | Server → Client | Status updates (e.g., container starting) |
pong | Server → Client | Heartbeat response |
If no preview container is running when you connect, one is automatically started.