billchurch
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 startAccess 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:latestRun the container exposing the default port:
docker run --rm -p 2222:2222 ghcr.io/billchurch/webssh2:latestTo pin to a specific release (example: webssh2-server-v2.3.2):
docker run --rm -p 2222:2222 \
ghcr.io/billchurch/webssh2:2.3.2The 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.2Configuration
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 startFor 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.100Custom port and terminal using interactive modal auth
http://localhost:2222/ssh?port=2244&sshterm=xterm-256colorDocker 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:latestNeed 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(ornpm ci) and continue using scripts such asnpm run devandnpm run build. The TypeScript sources remain the source of truth. - Release pipeline: Use
npm ci --omit=dev,npm run build, thennode dist/scripts/create-release-artifact.jsto producewebssh2-<version>.tar.gz,manifest.json, and a.sha256checksum. GNU tar is required to guarantee deterministic archives. - Packaged consumers (containers, downstream services): Download and verify the tarball, extract it, run
npm ci --omit=devfrom the extracted root (alongsidepackage.json), and start withNODE_ENV=production npm start. Theprestartscript 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!
