Terminal & Host Monitor UI
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal & Host Monitor UI provides a browser-based interface for server administration, real-time system resource monitoring, and remote file management. It integrates a pseudo-terminal (PTY) with synchronized side panels for monitoring and file operations, allowing administrators to execute shell commands and manage the host environment directly from the control plane.
Architecture and Connection Flow
The terminal system uses a WebSocket connection for bidirectional communication between the browser and the Go backend. The UI utilizes xterm.js for rendering the terminal emulator and FitAddon to handle responsive window resizing. The connection follows a specific security handshake requiring two-factor authentication (2FA) verification before establishing the PTY session.
The diagram shows the request flow from user interaction through security gates to the low-level PTY process.
Sources: web/src/pages/terminal-page.tsx:162-315, SECURITY.md:66-75
Connection Lifecycle
The connection state progresses through idle, connecting, connected, reconnecting, and closed. The system implements an exponential backoff strategy for automatic reconnection, ranging from 1 second up to 30 seconds, to handle transient network interruptions without losing the terminal buffer.
Sources: web/src/pages/terminal-page.tsx:21-31, web/src/pages/terminal-page.tsx:220-230
Security and Authentication
Terminal access is restricted by multiple layers of security to prevent unauthorized command execution.
- 2FA Requirement: The UI prompts for a 6-digit TOTP code if the session is not verified. This verification is required before the WebSocket handshake.
- Session Limits: The server enforces a maximum of two concurrent sessions and an absolute session limit of two hours.
- Privileged Execution: In production, the terminal operates via a privileged helper that creates a root PTY, granting full administrative access to the host.
- Audit Logging: All session open/close events are recorded in structured audit logs.
Sources: SECURITY.md:52-70, web/src/pages/terminal-page.tsx:98-115
| Security Feature | Implementation | Description |
|---|---|---|
| Authentication | JWT/Cookie + CSRF | Validates administrator session identity. |
| Step-up Auth | TOTP 2FA | Required to unlock terminal functionality. |
| Transport | Secure WebSocket (WSS) | Encrypts bidirectional terminal traffic. |
| Isolation | Minimized Environment | Excludes control-plane environment variables from the PTY. |
Sources: SECURITY.md:64-75, web/src/lib/api.ts:245-280
Host Resource Monitoring
The monitoring system provides real-time visibility into the server's health through two primary components: the HostMonitor (SSE-based) and the OpsPage (Polling-based).
Real-time Monitoring (HostMonitor)
The HostMonitor component subscribes to a Server-Sent Events (SSE) stream at /api/v1/terminal/metrics. It provides a compact view of:
- CPU Usage: Percentage usage per core and aggregate.
- Memory: Total, used, and cached memory.
- Network IO: Real-time upload and download rates.
- Load Averages: 1, 5, and 15-minute system loads.
The sequence illustrates the continuous data stream for real-time monitoring.
Sources: web/src/components/terminal/host-monitor.tsx:13-35, web/src/lib/api.ts:281-283
Detailed Metrics (OpsPage)
The OpsPage sub-tab performs periodic polling every 3000ms. It extends monitoring to include disk usage per filesystem and managed process resource consumption (CPU/RSS memory).
Sources: web/src/components/terminal/ops-page.tsx:11-40
File Management Integration
The FilePanel provides a graphical interface for the remote filesystem. It is technically integrated with the terminal session through OSC 7 sequence scanning.
- CWD Tracking: The UI scans terminal output for OSC 7 sequences emitted by the shell. This allows the file list to automatically navigate when a user types
cdin the terminal. - Shell Integration: When a user navigates via the GUI, the panel sends
cd <path>commands to the PTY, prefixed with a space to avoid polluting the shell history (assumingHISTCONTROL=ignorespace). - Operations: Supported operations include directory creation (
mkdir), file deletion (remove), and multipart file uploads.
Sources: web/src/pages/terminal-page.tsx:320-330, web/src/lib/api.ts:284-307, internal/api/terminal_files_test.go:175-235
Technical Specifications
Data Structures
The following structures define the communication between the UI and Backend:
// Terminal session status
type TerminalStatus = {
enabled: boolean
active_sessions: number
privileged: boolean
two_factor_verified: boolean
two_factor_verification_ttl_seconds: number
}
// System resource snapshot
type TerminalHostSample = {
timestamp: string
cpu_usage_pct: number
load1: number
load5: number
load15: number
memory_total_bytes: number
memory_used_bytes: number
processes: TerminalProcessResource[]
}
Sources: web/src/lib/api.ts:208-243
API Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/terminal/status | GET | Checks 2FA status and session availability. |
/api/v1/terminal/ws | WS | Bidirectional PTY stream. |
/api/v1/terminal/metrics | GET (SSE) | Real-time resource usage stream. |
/api/v1/terminal/files | GET/POST | Lists, downloads, and uploads files. |
/api/v1/terminal/files/remove | POST | Deletes files/directories. |
Sources: web/src/lib/api.ts:275-307
Conclusion
The Terminal & Host Monitor UI serves as the central administrative hub for host management. By combining a secure PTY session with real-time SSE metrics and a shell-synchronized file manager, it provides a comprehensive toolset for maintaining the server environment while enforcing strict security boundaries via 2FA and privileged helper processes.