Interactive terminal

High-trust WebSocket SSH terminal access.

Transport

The browser terminal uses /ws/devices/<device_id>/terminal. The backend authenticates the session, checks role and scope, validates the device, and coordinates terminal access with the same per-device SSH lane used by automation.

Same-origin protection

v2.0.0 validates WebSocket Origin before accepting terminal connections.

Idle timeout

SSH_TERMINAL_IDLE_MINUTES controls the interactive terminal idle timeout. The default in .env.example is 15 minutes.

Logging boundary

Password data and terminal content are not written into Job records.

A browser-based alternative to a separate SSH client

The integrated console covers the practical role often handled by desktop SSH tools such as PuTTY. An authorized engineer can select a managed switch and work with its native AOS command line without leaving Portivo, copying management addresses between tools or creating a separate shared credential path.

This is direct CLI access rather than a restricted command catalog. The switch prompt, command responses and interactive behavior are carried between the browser and the persistent SSH channel. Terminal resize events are forwarded to the remote session so the console adapts to the available workspace.

Connection lifecycle

1. The user signs in with a personal SSH-backed account.
2. The backend validates the WebSocket Origin and application session.
3. The assigned role must include terminal.use.
4. The selected switch must be enabled and inside the user's Site or Group scope.
5. Portivo attempts to acquire the device's terminal lease.
6. If another Job owns the device lane, the terminal waits or fails with a clear busy result.
7. After connection, the backend records terminal connect and disconnect audit events.
8. The session closes on user disconnect, authentication loss, transport failure or configured inactivity timeout.

Coordination with Jobs

The terminal and automation do not open competing SSH sessions against the same managed switch. A persistent console owns the same coordinator lane used by Jobs, audits, diagnostics and other live workflows. While a terminal is active, new live operations against that switch are blocked. While an operation owns the lane, a terminal connection is not allowed to overtake it.

Credentials and authorization

Terminal access requires a personal SSH-authenticated session. Local-only application authentication does not provide a switch password for the console. The active credential remains associated with the signed-in engineer, while the backend independently enforces the terminal capability and device scope.

Portivo does not copy terminal commands or output into Job records. Connect and disconnect events remain auditable, but the console content keeps the same high-trust boundary as a direct SSH client.

Operator responsibility

Catalog actions provide previews, structured parameters, Jobs and pending-configuration tracking. Commands entered manually in the terminal bypass those higher-level workflow controls because they are sent directly to the native switch CLI. Operators must review target identity, understand the AOS command, verify the result and save configuration deliberately when required.

Reverse proxy requirements

Normal pages can load even when WebSocket forwarding is incomplete. Production reverse proxies must support WebSocket upgrade headers and suitable idle behavior for /ws/devices/<device_id>/terminal. If the UI loads but the terminal cannot connect, validate the WebSocket proxy path before changing switch or credential settings.