Skip to content

Erupt Remote ​

erupt-remote bridges remote machines into the browser: VNC desktops rendered with noVNC, SSH shells with xterm.js, both over one WebSocket channel — no client-side tooling required.

Minimum version: 2.2.0

Security note

Remote access hands control of a machine to a browser tab. Grant it to trusted administrators only, and always run it over HTTPS/WSS in production.

Setup ​

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-remote</artifactId>
  <version>${erupt.version}</version>
</dependency>

Auto configuration adds a Remote Host (RemoteHost) table menu.

How it works ​

  1. Add a record in the Remote Host table with the address, port and protocol.
  2. Click the Connect row button to open the desktop or terminal page at the in-app route /remote/{id}.
  3. The server bridges a binary WebSocket (/erupt-remote) to the host's port.

VNC desktop (Windows)

VNC desktop on Windows

VNC desktop (macOS)

VNC desktop on macOS

SSH terminal

SSH terminal

Session Toolbar ​

The desktop and terminal pages share a toolbar along the top; a dot on the left shows the session state (connecting / connected / disconnected).

VNC desktop

ButtonWhat it does
KeysSends combinations the browser cannot pass through: Ctrl + Alt + Del, Alt + Tab, Tab, Esc, Print Screen
PasteSends the local clipboard to the remote desktop
ShotCaptures the current frame and downloads it
QualityBandwidth presets: Low bandwidth, Balanced, Best quality
PowerRemote power actions: Reboot, Reset, Shut down
View onlyWatch without sending any input
FitScale the frame to fit the window
FullscreenGo fullscreen
DisconnectEnd the session; the button becomes Reconnect

SSH terminal

ButtonWhat it does
Ctrl+CSends an interrupt to the remote process
PastePastes the local clipboard
ClearClears the screen
FullscreenGo fullscreen
DisconnectEnd the session; the button becomes Reconnect

SSH hosts with file transfer enabled also get a Files button that opens an SFTP panel next to the terminal — see SFTP File Transfer below.

SFTP File Transfer v2.3.0+ ​

The Files button on the SSH terminal page opens a side panel that works on the remote file system over the SFTP subsystem — nothing extra to install on the target host:

  • Browse: starts in the login user's home directory and descends into any directory; directories first, sorted by name, and symlinks are shown as what they point at so linked directories can be entered.
  • Upload: pick files with the button or drag-and-drop them onto the panel; shows progress, and an existing file of the same name is replaced.
  • Download: saves a remote file to the local machine as an attachment.
  • New folder: creates a subdirectory in the current directory.
  • Delete: removes one file, or one empty directory.
  • Insert path: types an entry's quoted path into the shell, ready for the next command.

The panel is shown only when the host has file transfer enabled. VNC hosts have no file channel (the RFB protocol has none) — configure the same machine as an SSH host when files need to move.

Per-host toggle ​

The File Transfer switch on the Remote Host record (RemoteHost.fileTransfer, column e_remote_host.file_transfer, BIT(1)) defaults to on and is shown only when the protocol is SSH. Turning it off:

  • removes the Files button from the terminal page;
  • makes every SFTP endpoint refuse with "File transfer is not enabled for this host";
  • leaves the shell itself untouched.

Use it for hosts whose users should type commands but not carry files in or out.

Security notes ​

ConcernHow it is handled
ConnectionsEvery call opens its own short-lived SSH session and closes it when done; it is never tied to the terminal WebSocket, so a dropped terminal does not kill a running download
Credentials and host keysShared with the terminal: the record's username / password / private key, the TOFU host-key policy (.erupt/remote_known_hosts) and connect-timeout-seconds. Remote permissions are those of the SSH login user
AuthorizationRe-checked on every call: erupt-upms token + the RemoteHost menu permission + host Enabled + Authorized Users + the File Transfer toggle. A host that was disabled, lost this user or had file transfer switched off after the page opened is refused on the next click
Path rulesEnforced by SftpPaths: paths must be absolute, . / .. are resolved lexically on the server, and any NUL character is rejected; names for new folders and uploads must be bare file names — no / or \, not . or ..
DeletionNever recursive: only a single file or an empty directory, and / is refused. Clearing a tree is a shell job, where the user sees what they are typing
UploadsThe raw request body is streamed straight into SFTP — no temp file, no multipart, hence no multipart size ceiling; size a reverse proxy's client_max_body_size accordingly

Endpoints ​

All routes live under /erupt-api/remote/sftp/{id} ({id} is the host record id), require the RemoteHost menu permission, and take absolute paths on the remote host:

MethodPathParamsWhat it does
GET/{id}/home—Absolute path of the login user's home directory
GET/{id}/lspathLists a directory; returns name / directory / size / mtime / mode
GET/{id}/downloadpathStreams a file as an attachment, _token in the URL; refuses directories
POST/{id}/uploadpath (directory), nameRequest body is the file content, written to path/name, replacing an existing file
POST/{id}/mkdirpath (directory), nameCreates directory name under path
DELETE/{id}pathRemoves one file or one empty directory

Host fields ​

FieldMeaning
Host NameDisplay name in the list
ProtocolVNC (desktop) or SSH (terminal)
HostIP address or hostname reachable from the erupt server
Port5900 for VNC, 22 for SSH
UsernameSSH login user, shown when the protocol is SSH
PasswordVNC: the server password (first 8 characters are used). SSH: the login password, or the passphrase when a private key is set
Private KeyPEM private key for SSH public-key authentication; takes precedence over the password
File Transfer v2.3.0+Whether to show the SFTP file panel (browse, upload, download) next to the SSH terminal. On by default, shown only when the protocol is SSH; when off, the Files button and the SFTP endpoints are disabled while the shell is untouched
EnabledDisabled hosts cannot be connected

Credentials are stored AES-GCM encrypted. The key comes from erupt.remote.secret-key, or is generated once into .erupt/remote.key when that is empty.

Security model ​

ConcernHow it is handled
Target addressResolved server-side from the record id; the browser can never choose where the connection goes
Authorizationerupt-upms token + the RemoteHost menu permission (checked on the ticket API and again on the WebSocket) + a one-time ticket
VNC passwordWhen a password is stored the server answers the RFB authentication itself, so the credential never reaches the browser. Without one (or against servers offering only other security types, e.g. macOS Apple Remote Desktop authentication) the handshake is relayed and noVNC prompts the user
SSH host keysTrust on first use, recorded in .erupt/remote_known_hosts; a changed key is refused
SessionsGlobal concurrency cap plus idle reaping

Configuration ​

yaml
erupt:
  remote:
    # Credential encryption key; inject it from the environment.
    # Multi-node deployments must share one value across every node
    secret-key: ${ERUPT_REMOTE_SECRET_KEY}
    # Global concurrent session limit
    max-sessions: 20
    # Sessions without browser input for this long are closed (minutes)
    idle-timeout-minutes: 30
    # TCP connect timeout towards the remote host (seconds)
    connect-timeout-seconds: 5

Nginx ​

As with erupt-terminal, forward the WebSocket upgrade for /erupt-remote:

nginx
location /erupt-remote {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

Preparing the Target Host ​

erupt-remote is a VNC client: the target host must already run a VNC server (SSH just uses the system's own sshd, nothing to install). Any RFB 3.3 / 3.7 / 3.8 server works.

Windows: install a VNC server yourself ​

Windows ships no VNC server — its built-in Remote Desktop speaks RDP, which is a different protocol — so one has to be installed:

SoftwareDownloadNotes
TightVNCtightvnc.com/download.phpFree and small, server included in the installer — the easiest start
UltraVNCuvnc.com/downloads/ultravnc.htmlFree, more features (file transfer, multi-monitor)
TigerVNCgithub.com/TigerVNC/tigervnc/releasesOpen source, cross-platform
RealVNC Serverrealvnc.com/download/vncCommercial, with a free tier for personal use

With TightVNC:

  1. Download the MSI for your architecture (tightvnc-x.x.x-gpl-setup-64bit.msi on 64-bit Windows).
  2. Choose Typical during setup and keep the TightVNC Server component selected.
  3. The installer asks for a password — what you enter under Password for Remote Access is the password to put in the erupt host record.
  4. The server then runs as a Windows service on port 5900; right-click the tray icon → Configuration to change the password or port later.
  5. Allow inbound connections on port 5900 in Windows Defender Firewall (the installer usually offers to add the rule).

Only the first 8 characters of a VNC password count

That is a limit of the RFB protocol itself, not of erupt. Keep the password to 8 characters to avoid the "I set a long password and it won't connect" puzzle.

macOS: turn on the built-in Screen Sharing ​

macOS has a VNC server built in; it only needs to be enabled for password access:

  1. Open System Settings → General → Sharing (older releases: System Preferences → Sharing).
  2. Turn on Screen Sharing.
  3. Click the ⓘ button next to it → Computer Settings….
  4. Tick "VNC viewers may control screen with password" and set a password (again, only the first 8 characters count).
  5. Make sure the Allow access for list includes the account you intend to use.

Then fill the host record with the Mac's IP, port 5900, and that VNC password.

Without a VNC password

Skip step 4 and macOS offers only Apple Remote Desktop authentication. The server cannot answer that on your behalf, so erupt relays the handshake and noVNC prompts in the browser for the macOS username and password — the connection still works, the credentials are simply not held server-side.

Linux: x11vnc or TigerVNC ​

  • Share the existing physical desktop: x11vnc, e.g. sudo apt install x11vnc, then x11vnc -display :0 -rfbauth ~/.vnc/passwd -forever (x11vnc -storepasswd writes the password file).
  • Start a separate virtual desktop: tigervnc-standalone-server — set a password with vncpasswd, run vncserver :1, and the port is 5901 (5900 + display number).

For pure command-line work, use the SSH protocol instead — no VNC server needed at all.

How this differs from erupt-terminal

erupt-terminal opens a shell on the host running erupt itself; erupt-remote connects to other managed machines, kept as records, authorized through a menu, and able to show a graphical desktop. Full comparison: erupt-terminal → How This Differs from erupt-remote.

Contributors

The avatar of contributor named as YuePeng YuePeng

Changelog

Released under the Apache-2.0 License.