Ultimate Terminal

TypeScript Node.js Socket.io React + Vite Docker .deb Playwright e2e

GitHub: stevenvo780/ultimate-terminal

---

What it is

Ultimate Terminal is a distributed terminal system that lets you open a shell on any Linux machine in your fleet from a single browser tab — no SSH juggling, no per-host clients. It follows a three-tier architecture:

Component	Role	Port
Nexus	Relay server. Authenticates workers and browser clients, routes I/O, manages sessions.	3002 (default)
Worker	Lightweight agent running on each target machine. Connects to Nexus via Socket.io.	N/A (outbound)
Client	React + Vite web UI. Lists all connected workers; opens terminal sessions; renders output.	5173 (dev) / 13003 (Docker)

Sessions persist in-memory inside Nexus while workers are online. Multiple browser tabs can join the same session simultaneously.

---

Key features

• One-command worker install — curl script pulls a prebuilt .deb (Ubuntu 20.04 / 22.04 / 24.04, Debian, Kali, Mint, Pop!) or compiles from source on other distros / GLIBC mismatches.
• JWT-authenticated API — setup token for first boot; per-worker API keys afterwards.
• Docker dev stack — docker-compose.dev.yml spins up 8 workers simultaneously to simulate load and validate the UI at scale.
• Docker prod stack — docker-compose.prod.yml with Nexus + Worker + Client, health-checked service dependencies, and a named volume for Nexus persistence.
• Playwright e2e tests — full terminal interaction tested end-to-end: login, list workers, open session, persist on reload.
• GitHub Actions CI — every worker-v* tag builds .deb packages for all three Ubuntu LTS versions in parallel and publishes them to GitHub Releases.

---

Architecture diagram

Browser (Client UI)
       │  WebSocket (Socket.io)
       ▼
  ┌─────────────────────────┐
  │    Nexus :3002           │  JWT auth · REST API · session relay
  │    SQLite persistence    │
  └──────────┬──────────────┘
             │  WebSocket (Socket.io)
    ┌────────┴────────┐
    │                 │
  Worker-01       Worker-N
  (your PC)       (VPS / homelab)

Each worker connects outbound to Nexus — no inbound firewall rules needed on target machines.

---

Installation

Worker — one-liner

curl -fsSL https://raw.githubusercontent.com/stevenvo780/ultimate-terminal/main/packaging/universal_install.sh \
  | sudo NEXUS_URL=<your-nexus-url> WORKER_NAME=<hostname> bash -s -- <API_KEY>

The installer detects your distro from /etc/os-release, downloads the matching .deb, and falls back to building from source on unsupported distros.

Dev setup (3 terminals)

git clone https://github.com/stevenvo780/ultimate-terminal.git
cd ultimate-terminal
cp .env.example .env            # fill in: NEXUS_JWT_SECRET, ADMIN_PASSWORD, WORKER_TOKEN
npm install

# Terminal 1
npm run start:nexus             # Nexus on :3002

# Terminal 2
npm run start:worker            # Worker connects to Nexus

# Terminal 3
npm run start:client            # React dev server on :5173

Docker dev (8 workers)

docker compose -f docker-compose.dev.yml up -d --build
# Nexus:  http://localhost:13002
# Client: http://localhost:13003
# Workers: worker-01 … worker-08 (all connected to Nexus)

View logs:

docker compose -f docker-compose.dev.yml logs -f nexus worker-01 worker-02

Docker prod (3 services)

cp .env.example .env   # set NEXUS_JWT_SECRET, ADMIN_PASSWORD, WORKER_TOKEN, VITE_NEXUS_URL
docker compose -f docker-compose.prod.yml up -d --build
# Nexus:  ${NEXUS_PORT:-13002}
# Client: ${CLIENT_PORT:-13003}

Production compose includes health-check on GET /api/auth/status before client starts.

Required environment variables

Always set these in .env before deploying:

• NEXUS_JWT_SECRET — strong random string (min 32 chars)
• ADMIN_PASSWORD — first-boot admin password
• WORKER_TOKEN — shared secret for worker authentication

Never commit the actual .env file.

---

API surface

REST endpoints (Nexus)

Endpoint	Description
POST /api/auth/setup	First-boot admin creation (requires NEXUS_SETUP_TOKEN if set)
POST /api/auth/login	Returns JWT for { username?, password }
POST /api/auth/register	Register additional users (validated against setup token)
POST /api/auth/password	Change password (authenticated)
GET /api/workers	List all registered workers
POST /api/workers	Register a new worker; returns API key
DELETE /api/workers/:id	Remove a worker (rejected if currently online)
GET /api/auth/status	Health-check used by Docker compose

Socket.io events

Direction	Event	Purpose
Client → Nexus	subscribe	Subscribe to a worker’s output stream
Client → Nexus	execute	Send a command to a worker
Client → Nexus	resize	Resize the terminal PTY
Client → Nexus	join-session	Join an existing session
Client → Nexus	leave-session	Leave a session
Nexus → Client	workers / worker-list	Live worker roster updates
Nexus → Client	session-list	Active session list for a worker
Nexus → Client	output	Terminal output from a worker
Nexus → Client	session-closed	Session terminated notification
Worker → Nexus	heartbeat	Keepalive
Worker → Nexus	output	PTY output chunks
Worker → Nexus	session-shell-exited	Shell process exited

---

Releasing

Releases are fully automated via GitHub Actions. To cut a new worker release:

git tag -a worker-v1.0.1 -m "Worker v1.0.1"
git push origin worker-v1.0.1

In about 5 minutes, Actions builds and publishes:

• ultimate-terminal-worker_<version>_ubuntu20.04_amd64_x86_64.deb
• ultimate-terminal-worker_<version>_ubuntu22.04_amd64_x86_64.deb
• ultimate-terminal-worker_<version>_ubuntu24.04_amd64_x86_64.deb
• worker-source-prebuilt.tar.gz

Three jobs run in parallel (one per Ubuntu LTS), each building inside the matching Ubuntu container so the embedded Node binary links against the correct GLIBC.

Version bumping rules

• PATCH — bug fix, no protocol change
• MINOR — new feature, backwards-compatible socket protocol
• MAJOR — breaking change in worker↔nexus protocol or env config

---

Testing

# Type-check all workspaces
npx tsc --noEmit --project nexus/tsconfig.json
npx tsc --noEmit --project worker/tsconfig.json

# Lint client
npm run lint --workspace=client

# Playwright e2e (requires full stack running)
# Nexus on :13002, Client on :13003, Worker connected
npx playwright test tests/terminal-e2e.spec.ts
npx playwright test tests/multi-client.test.ts

# Integration tests (vitest)
npm run test:e2e

The e2e suite covers: login, wait for worker online status, create session, execute command, verify output, persist session on reload.

---

Stack

Layer	Technology
Nexus	Node.js + TypeScript + Express + Socket.io
Worker	Node.js + TypeScript + node-pty
Client	React 18 + Vite + TypeScript
Auth	JWT (jsonwebtoken) + per-worker API keys
Persistence	better-sqlite3 (Nexus session metadata)
Packaging	@yao-pkg/pkg → .deb + systemd unit
Container	Docker Compose (dev: 8 workers; prod: 3 services)
CI	GitHub Actions (matrix: Ubuntu 20.04 / 22.04 / 24.04)
Tests	Playwright e2e + Vitest integration