WebSSH2 - Web SSH Client

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

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

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

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+)

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