A Websocket to SSH2 gateway using xterm.js, socket.io, ssh2
npm install webssh2-server!GitHub package.json version
!Docker Pulls
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.
- Node.js 22 LTS (Jod) or later
``bashClone repository
git clone https://github.com/billchurch/webssh2.git
cd webssh2
Access WebSSH2 at:
$3
- Preferred registry:
- Docker Hub mirror:
- Architectures: , linux/arm64Pull the latest build from GitHub Container Registry:
bash
docker pull ghcr.io/billchurch/webssh2:latest
`Run the container exposing the default port:
bash
docker run --rm -p 2222:2222 ghcr.io/billchurch/webssh2:latest
`To pin to a specific release (example:
):`bash
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:
bash
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):
bash
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-interactivenpm start
`For detailed configuration options, see Configuration Documentation.
Common Examples
$3
bash
http://localhost:2222/ssh/host/192.168.1.100
`$3
bash
http://localhost:2222/ssh?port=2244&sshterm=xterm-256color
`$3
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
`Need the Docker Hub mirror instead? Use
.Documentation
$3
- 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
$3
- Configuration Overview - Configuration methods and priority
- Environment Variables - Complete environment variable reference
- URL Parameters - Query string parameters
$3
- 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
$3
- Contributing Guide - How to contribute
- Development Setup - Setting up development environment
- API Documentation - WebSocket and REST APIs
$3
- Build & Packaging Guide - Reproducible release flow and manifest format
- Container Integration - Using the packaged bundle in images and CI
$3
- 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-, 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.If you like what I do and want to support me, you can buy me a coffee!
