Build a Java WebSSH Terminal with SpringBoot, WebSocket, and xterm.js

Introduction

A WebSSH terminal was required for a project. Existing open‑source solutions were mostly written in Python and depended on many external libraries, which made them unsuitable for a production environment where such dependencies cannot be guaranteed. A pure‑Java implementation was therefore created and released as an open‑source project.

Technology Stack

The solution relies on a long‑living bi‑directional channel, so WebSocket is used for real‑time data exchange. The backend is built with Spring Boot , the SSH client functionality is provided by jsch, and the front‑end terminal emulator is xterm.js. The overall stack is:

Spring Boot

WebSocket

JSch (Java SSH library)

xterm.js (browser terminal emulator)

Backend Workflow

The core server logic follows four sequential steps:

Initialize and establish the SSH connection : a JSch Session is created with the target host, authentication (password or key) is performed, and a ChannelShell is opened.

Process messages from the front‑end : incoming WebSocket frames contain user keystrokes or commands; the server writes these bytes to the ChannelShell output stream.

Forward terminal output to the front‑end : data read from the ChannelShell input stream is sent back through the WebSocket to the browser, where xterm.js renders it.

Close the connection : when the client disconnects or an error occurs, the ChannelShell and JSch Session are cleanly closed, and the WebSocket session is terminated.

Implementation Highlights

Spring Boot’s @EnableWebSocket and a custom WebSocketHandler are used to bind a WebSocket endpoint (e.g., /ws/ssh) to the SSH session.

JSch is configured with StrictHostKeyChecking=no for simplicity in development; production deployments should verify host keys.

Data is transferred as binary frames to avoid character‑encoding issues.

Threading: a dedicated thread reads from the SSH channel and pushes data to the WebSocket, while the WebSocket handler writes incoming data to the SSH channel.

Repository

The complete source code, including the Spring Boot configuration, WebSocket handler, and front‑end integration with xterm.js, is available at:

https://github.com/NoCortY/WebSSH