wraith/Remote-Spec.md
2026-03-12 16:59:34 -04:00

25 KiB

Planned Remote — Web-Based Terminal & Remote Desktop Client

Product Spec Sheet

Concept: A modern, self-hosted web application combining the best features of Termius (SSH/SFTP) and MobaXterm (SSH + RDP + SFTP browser) — accessible from any browser, no desktop client required.

Stack: Nuxt 3 (Vue 3 SSR) + NestJS backend + PostgreSQL

Target Users: MSP technicians, sysadmins, and IT teams who need unified remote access to SSH and RDP endpoints from any device


1. Feature Comparison — What We're Building Against

Termius (Desktop/Mobile SSH Client)

Feature Termius Free Termius Pro ($14.99/mo)
SSH / Mosh / Telnet
SFTP file transfer
Port forwarding
Multi-tab sessions
Split panes
Encrypted cloud vault
Cross-device sync
Team sharing (Team plan $29.99/user/mo)
Saved snippets/macros
FIDO2 / hardware key auth
RDP
SFTP browser (sidebar)

Key Termius strength: Beautiful cross-platform UI, encrypted credential sync. Key Termius weakness: No RDP. No SFTP sidebar browser. No web-based option.


MobaXterm (Windows Desktop Client)

Feature MobaXterm Free MobaXterm Pro ($69/license)
SSH / Mosh / Telnet / rlogin
RDP (Remote Desktop)
VNC
SFTP sidebar browser (auto-opens on SSH connect)
X11 server
Multi-tab sessions
Split panes
SSH tunnels (graphical manager)
Macros / saved commands (max 4) (unlimited)
Session limit 12 max Unlimited
Customizable / brandable
Portable (USB stick)
Web-based
Cross-platform (Windows only) (Windows only)

Key MobaXterm strength: All-in-one (SSH + RDP + VNC + SFTP + X11). The SFTP sidebar that auto-opens on SSH connect is killer UX. Key MobaXterm weakness: Windows only. Not web-based. Dated UI.


2. Vigilance Remote — Our Feature Set

Core Principle

Everything MobaXterm does for SSH + RDP + SFTP, but in a modern web browser with Termius-level UI polish.

2.1 SSH Terminal

Feature Implementation
SSH connections xterm.js (MIT) — the industry standard web terminal. Used by VS Code, Tabby, Theia, and hundreds of production applications. GPU-accelerated rendering, full Unicode/CJK/emoji support.
Backend proxy NestJS WebSocket gateway + ssh2 (npm) — Node.js SSH client library. Browser connects via WebSocket to NestJS, which proxies to the SSH target. No direct SSH from browser.
Authentication Password, SSH key (stored encrypted), SSH agent forwarding, FIDO2/hardware key
Multi-tab sessions Tab bar with session labels, color-coded by host group
Split panes Horizontal and vertical splits within a single tab (xterm.js instances in a flex grid)
Session recording Record terminal sessions as asciinema-compatible casts. Replay in browser. Audit trail for MSP compliance.
Saved snippets Quick-execute saved commands/scripts. Click to paste into active terminal.
Terminal theming Dark/light modes, custom color schemes, font selection, font size
Search in terminal Ctrl+F search through terminal scrollback buffer (xterm.js SearchAddon)
Copy/paste Ctrl+Shift+C / Ctrl+Shift+V, or right-click context menu

2.2 SFTP File Browser (MobaXterm's Killer Feature)

Feature Implementation
Auto-open on SSH connect When an SSH session connects, the SFTP sidebar automatically opens showing the remote filesystem. Exactly like MobaXterm.
Sidebar layout Left sidebar panel (resizable) showing remote filesystem as a tree. Main panel is the terminal.
File operations Browse, upload (drag-and-drop from desktop), download, rename, delete, chmod, create directory
Dual-pane mode Optional second SFTP panel for server-to-server file operations (drag between panels)
File editing Click a text file to open in an embedded code editor (Monaco Editor — same as VS Code). Save pushes back via SFTP.
Transfer queue Background upload/download queue with progress bars, pause/resume, retry
Backend ssh2-sftp-client (npm) or raw ssh2 SFTP subsystem. All file operations proxied through NestJS.

2.3 RDP (Remote Desktop)

Feature Implementation
RDP connections Apache Guacamole (guacd daemon + guacamole-common-js client library). Industry-standard, Apache-licensed, battle-tested web RDP.
Architecture Browser → WebSocket → NestJS → Guacamole protocol → guacd daemon → RDP to target. The NestJS backend acts as the tunnel between the JavaScript client and guacd.
Display HTML5 Canvas rendering via guacamole-common-js. Keyboard, mouse, and touch input forwarded.
Multi-monitor Support for multiple virtual displays
Clipboard sync Bidirectional clipboard between browser and remote desktop
File transfer Upload/download via Guacamole's built-in file transfer (drive redirection)
Audio Remote audio playback in browser
Resolution Auto-detect browser window size, or set fixed resolution
RDP settings Color depth, security mode (NLA/TLS/RDP), console session, admin mode, load balancing info
Session recording Guacamole native session recording (video-like playback of RDP sessions)

2.4 Connection Manager (Termius-style)

Feature Details
Host database Store hosts with: name, hostname/IP, port, protocol (SSH/RDP), credentials, group, tags, notes, color
Groups/folders Organize hosts into hierarchical groups (e.g., "RSM > Servers", "Filters Fast > Switches")
Quick connect Top bar with hostname input — type and connect without saving
Search Full-text search across all hosts, tags, and notes
Credential vault AES-256-GCM encrypted storage for passwords and SSH keys. Master password or Entra ID auth.
SSH key management Generate, import, export SSH keys. Associate keys with hosts.
Jump hosts / bastion Configure SSH proxy/jump hosts for reaching targets behind firewalls
Port forwarding Graphical SSH tunnel manager — local, remote, and dynamic forwarding
Tags & labels Color-coded tags for categorization (production, staging, dev, client-name)

2.5 Team & MSP Features

Feature Details
Multi-user User accounts with RBAC. Admin, Technician, Read-Only roles.
Entra ID SSO One-click Microsoft Entra ID integration (same pattern as Vigilance HQ and RSM ERP)
Shared connections Admins define connection templates. Technicians connect without seeing credentials.
Audit logging Every connection, command, file transfer logged with user, timestamp, duration.
Session sharing Share a live terminal session with a colleague (read-only or collaborative)
Client-scoped access MSP multi-tenancy — technicians see only the hosts for clients they're assigned to

3. Technology Stack

Frontend

Component Technology License
Framework Nuxt 3 (Vue 3 SSR) MIT
Terminal emulator xterm.js 5.x MIT
Terminal addons @xterm/addon-fit, @xterm/addon-search, @xterm/addon-web-links, @xterm/addon-webgl MIT
Code editor (SFTP) Monaco Editor MIT
RDP client guacamole-common-js Apache 2.0
UI library PrimeVue 4 or Naive UI MIT
State management Pinia MIT
CSS Tailwind CSS MIT
File upload Drag-and-drop with progress (native File API)

Backend

Component Technology License
Framework NestJS 10 MIT
SSH proxy ssh2 (npm) MIT
SFTP operations ssh2 SFTP subsystem (built into ssh2) MIT
RDP proxy guacd (Apache Guacamole daemon) Apache 2.0
Guacamole tunnel Custom NestJS WebSocket gateway → guacd TCP Apache 2.0
Database PostgreSQL 16 (hosts, users, credentials, audit logs) PostgreSQL License
Credential encryption AES-256-GCM (same pattern as Vigilance HQ)
WebSocket NestJS @WebSocketGateway (socket.io or ws) MIT
Auth JWT + Microsoft Entra ID (one-click setup)
Session recording asciinema format for SSH, Guacamole native for RDP MIT / Apache 2.0

Infrastructure

Component Technology
Deployment Docker Compose
Services app (Nuxt SSR + NestJS), guacd (Guacamole daemon), postgres, redis
Reverse proxy Nginx (WebSocket upgrade support required)
guacd Docker image guacamole/guacd — handles RDP/VNC protocol translation

4. Architecture

┌─────────────────────────────────────────────────────────────┐
│  Browser (Any device, any OS)                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  xterm.js     │  │ SFTP Browser  │  │ guac-client  │      │
│  │  (SSH term)   │  │ (file tree)   │  │ (RDP canvas) │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │ WebSocket        │ REST/WS         │ WebSocket     │
└─────────┼──────────────────┼─────────────────┼──────────────┘
          │                  │                 │
┌─────────┼──────────────────┼─────────────────┼──────────────┐
│  NestJS Backend (Docker)   │                 │              │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐      │
│  │  SSH Gateway  │  │ SFTP Service  │  │ Guac Tunnel  │      │
│  │  (ssh2 lib)   │  │ (ssh2 sftp)   │  │ (TCP→guacd)  │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │ SSH              │ SFTP            │ Guac Protocol │
└─────────┼──────────────────┼─────────────────┼──────────────┘
          │                  │                 │
          ▼                  ▼                 ▼
  ┌───────────────┐  ┌───────────────┐  ┌─────────────┐
  │  SSH Server    │  │  SSH Server    │  │   guacd      │
  │  (Linux/Unix)  │  │  (same host)   │  │  (Docker)    │
  └───────────────┘  └───────────────┘  └──────┬──────┘
                                                │ RDP
                                                ▼
                                        ┌───────────────┐
                                        │ RDP Server     │
                                        │ (Windows)      │
                                        └───────────────┘

5. Key Open Source Components

Component GitHub Stars License Purpose
xterm.js xtermjs/xterm.js 18K+ MIT Web terminal emulator — the industry standard. Used by VS Code.
ssh2 mscdex/ssh2 5.5K+ MIT Pure JavaScript SSH2 client/server. Powers the SSH proxy layer.
guacamole-common-js apache/guacamole-client 3.2K+ Apache 2.0 JavaScript RDP/VNC client. Renders remote desktop in HTML5 Canvas.
guacd apache/guacamole-server 3.2K+ Apache 2.0 Native daemon that translates RDP/VNC protocols to Guacamole protocol.
Monaco Editor microsoft/monaco-editor 42K+ MIT VS Code's editor component. For in-browser file editing via SFTP.
Tabby (reference) Eugeny/tabby 62K+ MIT Formerly Terminus — reference for SSH/SFTP web client architecture. Includes web app mode.

All components are MIT or Apache 2.0 licensed — zero GPL contamination, fully commercial-viable.


6. Competitive Positioning

Feature Termius Pro MobaXterm Pro Apache Guacamole Vigilance Remote
SSH Terminal
RDP
SFTP sidebar browser (killer feature)
Web-based (no install)
Cross-platform (native apps) (Windows only) (web) (web)
Modern UI (dated) (basic)
Team/MSP features (Team plan) (basic)
Entra ID SSO
Credential vault (master pw) (DB) (AES-256-GCM)
Session recording
Audit logging (basic) (comprehensive)
Multi-tenant (MSP)
Self-hosted N/A (desktop)
Embedded code editor (MobaTextEditor) (Monaco)
Price $14.99/mo/user $69 one-time Free Self-hosted (free) or SaaS

Vigilance Remote is the only solution that combines: web-based access + RDP + SSH + SFTP sidebar browser + modern UI + MSP multi-tenancy + Entra ID SSO + session recording + audit logging in a single self-hosted application.


7. Database Schema (High Level)

users              — id, email, name, role, entra_id, created_at
hosts              — id, name, hostname, port, protocol (ssh/rdp), group_id, tags, notes, color
host_groups        — id, name, parent_id (hierarchical)
credentials        — id, host_id, type (password/key/entra), encrypted_value, key_passphrase
ssh_keys           — id, user_id, name, public_key, encrypted_private_key, passphrase
sessions           — id, user_id, host_id, protocol, started_at, ended_at, recording_path
audit_logs         — id, user_id, action, target, details, ip_address, timestamp
port_forwards      — id, host_id, type (local/remote/dynamic), local_port, remote_host, remote_port
snippets           — id, user_id, name, command, tags
client_access      — id, user_id, client_id (MSP multi-tenant scoping)
settings           — id, key, value (system-wide config)

8. Build Estimate

Given the existing open-source components (xterm.js, guacd, ssh2, Monaco), the heavy lifting is integration, not invention. The core SSH terminal + SFTP browser + RDP via Guacamole + connection manager could be built as a focused 3-4 week project using the Commander doctrine.

Phase Duration Deliverables
Foundation Week 1 Nuxt 3 scaffold, NestJS backend, Docker Compose (app + guacd + postgres + redis), auth (Entra ID + local), connection manager CRUD
SSH + SFTP Week 2 xterm.js terminal with WebSocket proxy, multi-tab, split panes, SFTP sidebar browser with drag-drop upload/download, Monaco file editor
RDP Week 3 guacd integration, guacamole-common-js client, RDP canvas rendering, clipboard sync, session settings
Polish & MSP Week 4 Session recording/playback, audit logging, team features, MSP multi-tenant scoping, theming, keyboard shortcuts, snippets

This spec is ready for Claude Code. The open-source components are proven, the architecture is clean, and the integration patterns are well-documented. Point the XO at this spec and the result is a self-hosted MobaXterm replacement that runs in any browser.