Terminal VPS Backend — Architecture Brief

From: security-research sprint (2026-03-17) For: opportunity-tracker / Cloud Aegis embedded terminal (Item 6)

---

What was built

A Node.js WebSocket terminal server (ws + node-pty) is now implemented and ready for deployment on the shared Win19 VPS.

Server location

# In security-research repo:
infra/terminal-server/
  server.js       # WS server with JWT auth, shell selection, resize
  package.json    # ws, node-pty, jsonwebtoken

VPS details

Field	Value
Hostname	win-70drk9k58ml
Tailscale IP	100.111.119.102
Port	8088 (configurable via PORT env)
Specs	64-core EPYC, 64GB RAM
Network	Tailscale only — no public TLS needed

Authentication

• JWT passed as ?token=... query parameter on WebSocket upgrade
• Token generated by backend API: POST /api/terminal/token
• 5-minute TTL, HS256, shared secret via TERMINAL_JWT_SECRET env var
• Payload: { "sub": "<cf_identity>", "exp": ..., "iat": ... }

Shell selection

Query parameter ?shell=pwsh|bash:

• pwsh → powershell.exe (Win32) or pwsh (Linux)
• bash → wsl.exe (Win32) or /bin/bash (Linux)
• Default: PowerShell on Windows, $SHELL or /bin/bash elsewhere

Resize support

JSON message: {"type":"resize","cols":N,"rows":N} — handled by ptyProcess.resize()

Health check

GET /health → {"status":"ok","platform":"win32"}

---

Integration pattern for Cloud Aegis

To add a VPS terminal backend to Cloud Aegis:

1. Backend: Add a POST /api/terminal/token endpoint (Go equivalent)

   • Generate JWT with TERMINAL_JWT_SECRET, 5-min TTL
   • Return { "token": "...", "ws_url": "ws://100.111.119.102:8089" }
   • Use a different port (8089) to avoid collision with security-research (8088)

2. Frontend: In the terminal component, add a backend selector

   • "fly" → existing wss:// to Fly.io backend
   • "vps" → fetch token from step 1, then new WebSocket(ws_url + "?token=" + token + "&shell=bash")

3. VPS deployment: Run a second instance of the terminal server on port 8089

   # On the VPS:
   PORT=8089 TERMINAL_JWT_SECRET=<shared-secret> node server.js

Port allocation

Project	Port
security-research	8088
aegis (OT)	8089 (suggested)

---

Deployment (not yet done)

The server.js is written but not yet deployed to the VPS. Deployment steps:

# SSH into VPS via Tailscale
ssh win-70drk9k58ml

# Copy terminal-server directory
# Install deps: npm install
# Set env: TERMINAL_JWT_SECRET=<from 1Password>
# Run: node server.js (or use PM2/systemd for persistence)