Terminal

Browser-based WebSocket terminal access to online devices.

Overview

The terminal plugin provides interactive shell access to any online device directly from the Umoo web console. Sessions run over WebSocket with full PTY (pseudo-terminal) support, including:

• ANSI color and cursor control
• Window resize (SIGWINCH)
• Ctrl+C / Ctrl+Z signal forwarding
• Scrollback buffer

Prerequisites

1. The terminal plugin must be enabled for the tenant (Settings → Plugin Config → Terminal → Enabled).
2. The device must be Online (the agent must be connected to the platform).
3. Your user role must have the terminal/session:open permission (granted to operator and above by default).

Opening a Terminal

1. Navigate to Devices → [Device Name].
2. Click the Terminal tab.
3. The terminal connects automatically. You should see a shell prompt within a few seconds.

If the device is offline, the Terminal tab shows "Device is offline" and does not attempt to connect.

How It Works

Browser → WebSocket /api/v1/plugins/terminal/ws/{device_id}
        → Backend terminal plugin
        → NATS message bus
        → umoo-agent on device
        → PTY fork (shell process)

1. The browser opens a WebSocket connection to the backend.
2. The backend's terminal plugin authenticates the request (JWT + RBAC check for terminal/session:open).
3. A PTY session is created on the device via the NATS bus.
4. Keystrokes are forwarded from browser → backend → NATS → agent → PTY.
5. Output is streamed back: PTY → agent → NATS → backend → WebSocket → browser.

Active Sessions

Navigate to Settings → Plugin Config → Terminal or use the CLI to list active sessions:

# List active terminal sessions (requires terminal/session:read permission)
GET /api/v1/plugins/terminal/sessions

Sessions are listed with: session ID, device ID, connected user, start time.

Terminal Configuration

Configure shell and display settings per tenant and per device group:

Setting	Default	Description
Shell Path	/bin/sh	Shell executable on the device
Default Columns	80	Initial terminal width
Default Rows	24	Initial terminal height
Persistence	false	Keep session alive after browser disconnect
Enable Color Output	true	ANSI color support

Persistence: When enabled, sessions survive browser disconnects and can be reconnected. When disabled, closing the browser tab terminates the shell process.

Security

• All terminal sessions require terminal/session:open permission.
• Sessions are scoped to the authenticated tenant — you cannot open terminals to devices in other tenants.
• All keystrokes and output pass through the Umoo backend (not end-to-end encrypted between browser and device).
• Session events are written to the audit log.

Troubleshooting

Terminal shows "Device is offline":

• Check the device status in the device list.
• Verify the agent is running: systemctl status umoo-agent

Connection drops immediately:

• Check the terminal plugin is enabled in tenant plugin config.
• Verify the configured shell path exists on the device.
• Check backend logs for terminal plugin errors.

"Permission denied" on connect:

• Your role may not have terminal/session:open. Contact your tenant admin.