Self-hosted service
billchurch/webssh2 avatar
billchurch/webssh2

webssh2: a WebSocket to SSH2 gateway you run yourself

Web SSH Client using ssh2, socket.io, xterm.js, and express. webssh webssh2

2,784 stars581 forksTypeScriptMIT

At a glance

What is it?
webssh2 puts an xterm.js terminal in the browser and proxies it to a real SSH server through ssh2 on the Node.js side. It is for engineers who need shell access from a locked-down browser, and it is best treated as a network appliance, not a SaaS product.
Who is it for?
Adopt webssh2 if you need a browser terminal you control, you can run Node.js 22 or the ghcr.io/billchurch/webssh2 image, and you are prepared to put authentication and TLS in front of it. Do not adopt it as an internet-facing gateway on its own, and do not expect host key verification to protect connections until you explicitly enable it, since the README states the feature is disabled by default.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 27 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • billchurch/webssh22,784 ★ · +8
Star history
Repository2026-10-042026-11-21
billchurch/webssh22.8k2.8k

8 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem webssh2 solves, and who actually needs it

SSH clients are desktop software. That is fine until the machine you are sitting at is a managed laptop with no package manager, a jump host you reach through a browser-only VPN portal, or a tablet in a lab. webssh2 exists for those cases: it runs a Node.js process that accepts a Socket.io connection from a browser, opens an SSH2 session to a target host on your behalf, and pipes bytes between the two. The package description in package.json says exactly that: a Websocket to SSH2 gateway using xterm.js, socket.io, ssh2.

The intended audience is narrower than the feature list suggests. This is infrastructure for a team that already runs servers and wants a terminal reachable from a browser on its own network. It is not a hosted bastion service, and the README does not present it as one. If your requirement is a cloud jump host with per-user audit trails and policy, webssh2 gives you the transport and leaves the surrounding controls to you.

How the gateway moves bytes between xterm.js and ssh2

There are two halves. The browser half is the webssh2_client bundle, which the server ships as a matching npm dependency (version 5.4.2 in package.json for server 5.2.1). That bundle carries xterm.js and the Socket.io client. The server half is TypeScript, compiled to dist, and it holds express, socket.io, and ssh2 1.17 as direct dependencies.

The data flow is a straight proxy. The browser opens a Socket.io connection to the express server; the server uses ssh2 to authenticate to the target host and open a shell channel; keystrokes travel from xterm.js through Socket.io to the ssh2 channel, and output travels back. Because the SSH connection originates from the server, the browser never speaks SSH itself and the target host sees the server's IP, not the user's. That single fact drives most deployment decisions: the webssh2 host needs network reach to every machine you intend to reach through it.

Configuration follows 12-factor style. Environment variables take precedence, with a config file as an alternative, and URL query parameters can supply per-connection values. The examples in the README show both: a path form such as /ssh/host/192.168.1.100, and a query form such as /ssh?port=2244&sshterm=xterm-256color.

Installing webssh2 with Docker and opening a first session

The fastest path is the published container. The README lists ghcr.io/billchurch/webssh2 as the preferred registry and docker.io/billchurch/webssh2 as a mirror, built for linux/amd64 and linux/arm64. Pull and run it with the default port exposed:

bash
docker pull ghcr.io/billchurch/webssh2:latest
docker run --rm -p 2222:2222 ghcr.io/billchurch/webssh2:latest

After the container starts, the terminal is served at http://localhost:2222/ssh. The README notes that /telnet is the alternate entry point when telnet support is enabled, and that telnet is disabled by default.

For a configuration-driven deployment, pass environment variables instead of building anything. This example comes from the README's Docker section and sets a default host, a modern algorithm preset, and an explicit authentication allowlist:

bash
docker run --rm -it \
  -p 2222:2222 \
  -e WEBSSH2_SSH_HOST=ssh.example.com \
  -e WEBSSH2_SSH_ALGORITHMS_PRESET=modern \
  -e WEBSSH2_AUTH_ALLOWED=password,publickey \
  ghcr.io/billchurch/webssh2:latest

If you prefer to run from source, the README's Quick Start requires Node.js 22 LTS or later and gives four commands: git clone https://github.com/billchurch/webssh2.git, cd webssh2, npm install --production, npm start. One caveat visible in the repository rather than the README: package.json declares a prestart script (node scripts/prestart.js) and a postinstall hook, so npm start is not a bare node invocation. The Dockerfile explains the project's own reasoning for skipping lifecycle scripts during image builds, re-running only the better-sqlite3 rebuild. If you build from source, read scripts/postinstall.js before you run it in a shared environment.

Host key verification is off until you turn it on

The README is direct about this: host key verification is disabled by default and must be explicitly enabled in configuration. When enabled, webssh2 compares the remote server's public key against a known-good key before letting the connection proceed, using the same trust-on-first-use model as OpenSSH. The repository backs that up with a better-sqlite3 dependency described in the Dockerfile comments as the host-key store.

This is the single most consequential default in the project. A gateway that accepts any host key is exposed to man-in-the-middle attacks on the path between the webssh2 server and the target, and the browser user has no way to see the key themselves, because the SSH handshake happens server-side. OpenSSH prompts a human; webssh2 has no human in that position unless the operator configures one. Treat the default as acceptable only on a network segment you fully control.

The same logic applies to authentication. The README's configuration example exports WEBSSH2_AUTH_ALLOWED=password,keyboard-interactive and notes that the default allows all methods. If your fleet uses keys, an allowlist that still permits password authentication is a weaker posture than you probably intend.

Where webssh2 is the wrong tool

webssh2 proxies through a server you operate, so every session consumes a connection from that host and every target must be reachable from it. On a large fleet with per-user key material, that means distributing credentials to the gateway rather than to the user, which is a different trust model than giving each engineer their own SSH key and agent. If your security model depends on the user's key never leaving their machine, this architecture fights you.

The project also carries a version coupling that matters. The README's compatibility matrix maps server 5.x to client ^4.0.0 and server 4.x to client ^3.x, and notes that headerStyle and header.color were removed in the client 4 line. Operators using the published Docker image or installing webssh2 from npm get the matching client automatically. The matrix only matters if you self-build the client, link a local fork, or pin a client version different from the one the server declares. That is a real constraint for anyone maintaining a themed fork.

Finally, the README does not document rollback or a downgrade path. The migration guide is linked under Getting Started, but its contents are not reproduced there, so plan upgrades with the breaking changes document open rather than assuming reversibility.

How webssh2 differs from Sshwifty and ttyd

The closest alternatives people search for alongside webssh2 are Sshwifty and the ttyd/WeTTY family, and the split is architectural. webssh2 is a Node.js and TypeScript application built on express, socket.io, and the ssh2 library; it ships as an npm package and an official container, and it carries a browser client bundle as a versioned dependency. If your team already runs Node services and wants a configuration surface made of environment variables, that fits naturally.

Sshwifty takes a different route: a self-contained web SSH and telnet client distributed as a single binary, which removes the Node.js runtime and the npm dependency tree from your deployment. The trade is a different configuration model and no npm package to pin. ttyd and WeTTY solve a related but distinct problem, exposing a terminal over the web, and ttyd in particular is commonly used to put a shell or an arbitrary command behind a browser rather than to proxy SSH credentials on the user's behalf.

The practical question is whether you want an application you configure and extend in TypeScript, or a binary you drop on a host. webssh2's feature set (exec channel, environment forwarding, subnet restrictions, optional telnet, SFTP from v2.6.0) is broad, and breadth in a Node application means a dependency tree to track. The Dockerfile's own comments about skipping lifecycle scripts so a compromised dependency cannot execute arbitrary code during the build show the maintainers think about that surface.

Licence, maintenance and the cost of staying current

webssh2 is MIT licensed, and package.json marks it private: false with dist, LICENSE, README.md and ChangeLog.md as the published files. MIT is permissive, so embedding it in a commercial internal tool is straightforward from a licensing standpoint; this is not legal advice, and if you redistribute a modified client bundle you should read the licence text yourself rather than rely on a summary.

The maintenance signal is healthy by the only measure available here: the last push to main was on 2026-08-18, and the most recent release, webssh2-server v5.2.1, carries the same date, with v5.2.0 on 2026-07-30 and v5.1.0 on 2026-07-28. Three releases in three weeks is a project that ships. The upgrade cost is dominated by the client/server pairing described in the compatibility matrix, plus whatever the breaking changes document lists between your pinned version and the target. Because the client arrives as an npm dependency, upgrading the server pulls a client with it, which is convenient until you have forked the client.

Editorial conclusion

Adopt webssh2 if you need a browser terminal you control, you can run Node.js 22 or the ghcr.io/billchurch/webssh2 image, and you are prepared to put authentication and TLS in front of it. Do not adopt it as an internet-facing gateway on its own, and do not expect host key verification to protect connections until you explicitly enable it, since the README states the feature is disabled by default. Before rollout, verify three things: that WEBSSH2_AUTH_ALLOWED lists only the methods you actually use, that your client and server majors match the published compatibility matrix, and that your reverse proxy terminates TLS and enforces its own access control. The project's own answer to the trust problem, a better-sqlite3 host key store, is opt-in, so the default posture is the thing to check first.

Frequently asked questions

What is webssh2 used for?

It is an HTML5 web terminal and SSH client. A Node.js server accepts a Socket.io connection from the browser and proxies it over ssh2 to a target SSH host, with optional telnet support.

Can I browse the web over SSH with webssh2?

No. webssh2 gives you a shell in the browser by proxying an SSH session; it is not a web proxy and the README does not describe tunnelling HTTP traffic through it.

What does SSH in a website mean for webssh2?

Here it means the SSH handshake happens on the server, not in the browser. The browser speaks Socket.io to webssh2, and webssh2 speaks SSH to the target host, so the target sees the gateway's address.

Official sources

  1. billchurch/webssh2 on GitHub
  2. Issues
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/billchurch-webssh2.svg)](https://hysenlabs.com/projects/billchurch-webssh2)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/billchurch-webssh2.svg)](https://hysenlabs.com/projects/billchurch-webssh2)

Was this useful?