Remote Access Workflow¶

This page explains how to open a secure browser-based terminal on a remote device.

How It Works¶

graph TD
    BR["Browser (ThingsBoard Terminal Widget)"]
    TXP["Terminal Proxy (Tenant-Stack · Node.js)"]
    TTD["ttyd on device (ws://10.8.0.2:7681)"]
    SH["/bin/bash (PTY)"]

    BR -->|"WSS wss://tenant.example.com/terminal?deviceId=device-001&token=JWT"| TXP
    TXP -->|"1. validate Keycloak JWT (JWKS from Tenant Keycloak)"| TXP
    TXP -->|"2. check preferred_username role (cdm-operator / cdm-admin)"| TXP
    TXP -->|"3. look up device-001 → WireGuard IP (10.8.0.2)"| TXP
    TXP -->|"4. proxy WebSocket (WireGuard VPN)"| TTD
    TTD --> SH

The device is only reachable via the WireGuard VPN — it has no direct internet exposure.

Prerequisites¶

• The device must be enrolled and connected to the Tenant WireGuard VPN.
• ttyd must be running on the device (port 7681, bound to the WireGuard interface only).
• The terminal-proxy (Tenant-Stack) must be running and healthy.
• The operator must have a valid Keycloak JWT with role cdm-operator or cdm-admin in the Tenant realm.

Opening a Terminal from ThingsBoard¶

1. In ThingsBoard, open the dashboard for your device.
2. The Terminal custom widget is embedded in the dashboard.
3. The widget automatically fetches the JWT from ThingsBoard's auth context.
4. Click Connect — a terminal session opens in the browser.

Opening a Terminal Directly (curl / wscat)¶

For testing or automation:

# Install wscat
npm install -g wscat

# Get a Keycloak token from the Tenant Keycloak
TENANT=https://tenant.example.com
TOKEN=$(curl -s -X POST \
  "$TENANT/auth/realms/tenant-acme/protocol/openid-connect/token" \
  -d "grant_type=password&client_id=terminal-proxy&username=operator&password=<pw>" \
  | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)

# Connect to the terminal proxy
wscat --connect "$TENANT/terminal?deviceId=device-001&token=$TOKEN"

ttyd Setup on a Real Device¶

Install and configure ttyd so it only listens on the WireGuard interface:

# On the device (run as root)
bash /opt/cdm/terminal/setup.sh

The setup script:

1. Installs ttyd from the system package manager.
2. Creates /etc/systemd/system/ttyd.service bound to the wg0 interface.
3. Sets the credential: username cdm, password from CDM_TTYD_PASSWORD env var.
4. Enables and starts the service.

Terminal Proxy Configuration¶

Troubleshooting¶