WebSSH2 - Web SSH Client

WebSSH2 is an HTML5 web-based terminal emulator and SSH client with optional telnet support. It uses SSH2 as a client on a host to proxy a Websocket / Socket.io connection to an SSH2 server.

Sponsors

WebSSH2 development is supported by Tailwind Resource Group, an engineering-led IT services firm specializing in application delivery, zero trust security, and identity for federal and commercial customers.

Compatibility

WebSSH2 server bundles a matching version of the webssh2_client browser bundle as an npm dependency. The compatibility matrix below tracks which client major each server major ships with.

Operators using the published Docker image or installing webssh2 from npm get the correct client automatically. The matrix matters if you self-build the client, link a local fork, or pin to a different client version than the server's dependency declares.

Quick Start

Requirements

• Node.js 22 LTS (Jod) or later

Installation

# Clone repository
git clone https://github.com/billchurch/webssh2.git
cd webssh2

# Install dependencies
npm install --production

# Start server
npm start

Access WebSSH2 at: http://localhost:2222/ssh (or http://localhost:2222/telnet if telnet is enabled)

Official Containers

• Preferred registry: ghcr.io/billchurch/webssh2
• Docker Hub mirror: docker.io/billchurch/webssh2
• Architectures: linux/amd64, linux/arm64

Pull the latest build from GitHub Container Registry:

docker pull ghcr.io/billchurch/webssh2:latest

Run the container exposing the default port:

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

To pin to a specific release (example: webssh2-server-v2.3.2):

docker run --rm -p 2222:2222 \
  ghcr.io/billchurch/webssh2:2.3.2

The same tags are available on Docker Hub if you prefer the legacy namespace:

docker run --rm -p 2222:2222 docker.io/billchurch/webssh2:2.3.2

Configuration

WebSSH2 prefers environment variables for configuration (following 12-factor app principles):

# Basic configuration
export WEBSSH2_LISTEN_PORT=2222
export WEBSSH2_SSH_HOST=ssh.example.com
export WEBSSH2_HEADER_TEXT="My WebSSH2"
# Allow only password and keyboard-interactive authentication methods (default allows all)
export WEBSSH2_AUTH_ALLOWED=password,keyboard-interactive

npm start

For detailed configuration options, see Configuration Documentation.

Common Examples

Connect to a specific host using HTTP Basic Auth

http://localhost:2222/ssh/host/192.168.1.100

Custom port and terminal using interactive modal auth

http://localhost:2222/ssh?port=2244&sshterm=xterm-256color

Docker with environment variables

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

Need the Docker Hub mirror instead? Use docker.io/billchurch/webssh2:latest.

Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions
• Docker Setup - Docker and Kubernetes deployment
• Migration Guide - Upgrading from older versions

Configuration Documentation

• Configuration Overview - Configuration methods and priority
• Environment Variables - Complete environment variable reference
• URL Parameters - Query string parameters

Feature Documentation

• Authentication Methods - Password, key-based, and SSO
• Private Key Authentication - SSH key setup and usage
• Exec Channel - Non-interactive command execution
• Environment Forwarding - Pass environment variables
• Host Key Verification - MITM protection and key management
• Telnet Support - Optional telnet for legacy devices

Development

• Contributing Guide - How to contribute
• Development Setup - Setting up development environment
• API Documentation - WebSocket and REST APIs

Release Artifacts

• Build & Packaging Guide - Reproducible release flow and manifest format
• Container Integration - Using the packaged bundle in images and CI

Reference

• Troubleshooting - Common issues and solutions
• Breaking Changes - Version migration notes

Features

• 🌐 Web-based SSH - No client software required
• 🔐 Multiple Auth Methods - Password, private key, keyboard-interactive
• 📱 Responsive Design - Works on desktop and mobile
• 🎨 Customizable - Themes, fonts, and terminal settings
• 🔌 WebSocket - Real-time bidirectional communication
• 🐳 Docker Ready - Official Docker images available
• 🔧 Exec Channel - Run commands without opening a shell
• 🌍 Environment Variables - Pass custom environment to SSH sessions
• 🛡️ Subnet Restrictions - IPv4/IPv6 CIDR subnet validation for access control
• 📁 SFTP Support - File transfer capabilities (v2.6.0+)
• 📡 Telnet Support - Optional telnet protocol for legacy devices (disabled by default)

Host Key Verification

Host key verification protects SSH connections against man-in-the-middle (MITM) attacks by validating the public key presented by the remote SSH server. When enabled, WebSSH2 compares the server's host key against a known-good key before allowing the connection to proceed. This is the same trust-on-first-use (TOFU) model used by OpenSSH.

The feature is disabled by default and must be explicitly enabled in configuration.

Configuration

Add the hostKeyVerification block under ssh in config.json:

{
  "ssh": {
    "hostKeyVerification": {
      "enabled": true,
      "mode": "hybrid",
      "unknownKeyAction": "prompt",
      "serverStore": {
        "enabled": true,
        "dbPath": "/data/hostkeys.db"
      },
      "clientStore": {
        "enabled": true
      }
    }
  }
}

Modes of Operation

The mode setting is a shorthand that controls which key stores are active. Explicit serverStore.enabled and clientStore.enabled flags override the mode defaults when set.

Unknown Key Actions

When a host key is not found in any enabled store, the unknownKeyAction setting determines what happens:

Environment Variables

All host key settings can be configured via environment variables. Environment variables override config.json values.

SQLite Server Store Setup

The server store uses a SQLite database that is opened in read-only mode at runtime. You must create and populate the database ahead of time using the seeding script (see below).

Creating the database:

# Probe a host to create and populate the database
npm run hostkeys -- --host ssh.example.com

The script automatically creates the database file (and parent directories) at the configured dbPath if it does not exist.

Bulk seeding from a hosts file (capped at 1000 entries by default):

# Probe each line of hosts.txt; refuses files with more than 1000 entries.
npm run hostkeys -- --hosts hosts.txt
# Override the cap for a legitimate large rollout:
npm run hostkeys -- --hosts hosts.txt --max-hosts 5000

Importing from an OpenSSH known_hosts file:

The --known-hosts command is a dry-run by default — it prints a preview of the parsed entries and exits without touching the database. This is a deliberate safety gate because every entry in the trust store is trusted unconditionally by the server at startup. Inspect the preview, verify the source is what you expected, then re-run with --commit:

# Preview only (no writes)
npm run hostkeys -- --known-hosts ~/.ssh/known_hosts

# After verifying the preview, commit:
npm run hostkeys -- --known-hosts ~/.ssh/known_hosts --commit

Docker volume mounting:

When running in Docker, mount a volume to the directory containing your database so it persists across container restarts. The mount path must match the dbPath value in your configuration:

docker run --rm -p 2222:2222 \
  -v /path/to/local/hostkeys:/data \
  -e WEBSSH2_SSH_HOSTKEY_ENABLED=true \
  -e WEBSSH2_SSH_HOSTKEY_DB_PATH=/data/hostkeys.db \
  ghcr.io/billchurch/webssh2:latest

Where can the database file live?

For safety, the seeding CLI refuses to create new parent directories outside an allowlist:

• /data (the documented default)
• The directory of WEBSSH2_SSH_HOSTKEY_DB_PATH if set
• The directory of ssh.hostKeyVerification.serverStore.dbPath in config.json if set
• The current working directory

Pointing --db at a path whose parent directory already exists is always allowed. The restriction only applies when the seeder would have to create new directories outside the allowlist.

Seeding from inside the production container

WARNING: You must mount /data (named volume or bind mount) before running any seeding commands inside a production container. The image deliberately does not declare VOLUME /data — without an operator- provided mount, the seeded hostkeys.db is written to the container's writable layer and is destroyed by docker rm. The absent VOLUME directive is intentional: silent anonymous-volume data loss (which is what Docker does when a VOLUME is declared but unmounted) is a worse failure mode than container-fs loss, because the latter is an obvious operator mistake while the former looks like everything is working until the container is removed.

The production image ships the compiled CLI at dist/scripts/host-key-seed.js and exposes it via npm run hostkeys:prod. The dev-only npm run hostkeys script uses tsx (a devDependency that is not present in the image), so inside the container you must always use :prod.

Seed against a running container (most common):

docker exec <container> npm run hostkeys:prod -- --host ssh.example.com

One-shot pre-seed before the first container start:

docker run --rm \
  -v hostkeys-data:/data \
  -e WEBSSH2_SSH_HOSTKEY_DB_PATH=/data/hostkeys.db \
  ghcr.io/billchurch/webssh2:latest \
  npm run hostkeys:prod -- --host ssh.example.com

Troubleshooting:

• EACCES: permission denied writing /data/hostkeys.db — the bind-mounted host directory is not writable by uid 1000 (the node user inside the container). Either chown 1000:1000 /path/on/host/hostkeys on the host before mounting, or switch to a named volume managed by the Docker daemon (named volumes inherit image ownership and avoid this).
• The seeded database "disappears" between container restarts — the operator forgot to mount /data. Verify with docker inspect <container> that /data is listed under Mounts as a bind or volume source, not a container-local path. The examples/docker-compose.yml file shows the expected named-volume setup.

Seeding Script Usage

The npm run hostkeys command manages the SQLite host key database. It probes remote hosts via SSH to capture their public keys and stores them for later verification.

npm run hostkeys -- --help

Probe a single host (default port 22):

npm run hostkeys -- --host ssh.example.com

Probe a host on a non-standard port:

npm run hostkeys -- --host ssh.example.com --port 2222

Bulk import from a hosts file (one host[:port] per line, # comments allowed; capped at 1000 entries by default — see --max-hosts):

npm run hostkeys -- --hosts servers.txt

Import from an OpenSSH known_hosts file (dry-run by default — add --commit to actually write):

# Preview only (no writes)
npm run hostkeys -- --known-hosts ~/.ssh/known_hosts

# After verifying the preview, commit:
npm run hostkeys -- --known-hosts ~/.ssh/known_hosts --commit

List all stored keys:

npm run hostkeys -- --list

Remove all keys for a host:port pair:

npm run hostkeys -- --remove ssh.example.com:22

Use a custom database path:

npm run hostkeys -- --list --db /custom/path/hostkeys.db

If --db is not specified, the script reads dbPath from config.json, falling back to /data/hostkeys.db.

Socket Protocol Reference

The following Socket.IO events are used for host key verification. This reference is intended for CLI clients and third-party implementors integrating with the WebSSH2 WebSocket protocol.

Server to Client:

Client to Server:

Troubleshooting

Feature appears to have no effect: Host key verification is disabled by default (enabled: false). Set WEBSSH2_SSH_HOSTKEY_ENABLED=true or "enabled": true in config.json to activate it.

Database not found at runtime: The server store opens the database in read-only mode. If the file at dbPath does not exist, all lookups return "unknown" and the store operates in degraded mode. Run npm run hostkeys to create and seed the database before starting the server.

Host key mismatch: A hostkey:mismatch event means the SSH server is presenting a different key than what is stored in the database. This can happen after a legitimate server reinstall or key rotation. To resolve:

1. Verify the new key is legitimate (contact the server administrator).
2. Remove the old key: npm run hostkeys -- --remove host:port
3. Re-probe the host: npm run hostkeys -- --host <hostname> --port <port>

If you receive frequent mismatches for hosts you did not change, investigate for potential MITM attacks.

Client verification times out: When using prompt mode, the client has 30 seconds to respond to a hostkey:verify event. If the client does not respond in time, the connection is refused. Ensure the client application handles the hostkey:verify Socket.IO event.

Telnet Support

WebSSH2 includes optional telnet protocol support for connecting to legacy devices such as network switches, routers, and older systems that don't support SSH. Telnet is disabled by default and must be explicitly enabled.

Security Warning: Telnet transmits all data in plain text, including credentials. Only use on trusted, isolated networks.

Enabling Telnet

# Via environment variable
docker run --rm -p 2222:2222 \
  -e WEBSSH2_TELNET_ENABLED=true \
  ghcr.io/billchurch/webssh2:latest

Or in config.json:

{
  "telnet": {
    "enabled": true
  }
}

Once enabled, access telnet at http://localhost:2222/telnet or connect to a specific host at http://localhost:2222/telnet/host/192.168.1.1.

Telnet Features

• Expect-style authentication - Configurable regex patterns for login/password prompt detection
• IAC negotiation - Full RFC 854/857/858/1073/1091 support (ECHO, SGA, NAWS, TERMINAL_TYPE)
• Subnet restrictions - Limit which hosts can be reached via telnet
• Security warnings - Visual banner in the client UI reminding users of telnet's insecurity

For full configuration options, see Environment Variables and Config JSON.

Release Workflow Overview

• Development: Run npm install (or npm ci) and continue using scripts such as npm run dev and npm run build. The TypeScript sources remain the source of truth.
• Release pipeline: Use npm ci --omit=dev, npm run build, then node dist/scripts/create-release-artifact.js to produce webssh2-<version>.tar.gz, manifest.json, and a .sha256 checksum. GNU tar is required to guarantee deterministic archives.
• Packaged consumers (containers, downstream services): Download and verify the tarball, extract it, run npm ci --omit=dev from the extracted root (alongside package.json), and start with NODE_ENV=production npm start. The prestart script detects the precompiled bundle and skips rebuilding.

Support

If you like what I do and want to support me, you can buy me a coffee!

License

MIT License