WebSSH - Browser-based SSH Client

Multi-connection SSH client that runs entirely in your browser with JWT authentication, SFTP file manager, and automatic session recording. Built with Python, Paramiko, WebSockets, and xterm.js.

Perfect for: System administrators, DevOps engineers, developers who need quick SSH access from any browser without installing clients.

Features

Multi-connection support - Manage multiple SSH connections simultaneously through a sidebar interface
JWT Authentication - Secure token-based authentication (configurable users, 8-hour token expiry)
Password & SSH Key authentication - Support for both password and SSH key (RSA, Ed25519, ECDSA)
SFTP File Manager - Built-in file manager with drag-and-drop upload/download, directory navigation, and file operations
Terminal emulator - Full xterm.js terminal experience with proper scrolling and colors
Session Recording - Automatic recording of SSH sessions in asciinema format with playback and configurable retention
Auto-Lock & Auto-Disconnect - Automatic session locking after inactivity (configurable per connection) and auto-disconnect for extended inactivity
Single port deployment - All services (HTTP API, WebSocket SSH, WebSocket SFTP) run through one port
Multi-architecture - Images available for linux/amd64 and linux/arm64
Lightweight - Images with integrated Caddy reverse proxy included

Quick Start

Single Container

docker run -d \
  -p 8080:8080 \
  -e WEBSSH_USERS=admin:admin \
  -e MAX_UPLOAD_SIZE=100M \
  --name webssh \
  --restart unless-stopped \
  danaildr/webssh:latest

Then open http://localhost:8080 in your browser.
Default credentials: admin / admin

With Persistent Data & Auto-Lock

docker run -d \
  -p 8080:8080 \
  -v webssh_data:/data \
  -e WEBSSH_USERS=user1:pass1,user2:pass2 \
  -e JWT_SECRET=your-256-bit-secret-here \
  -e MAX_UPLOAD_SIZE=500M \
  -e RECORDING_ENABLED=true \
  -e RECORDING_RETENTION_DAYS=30 \
  --name webssh \
  --restart unless-stopped \
  danaildr/webssh:latest

Note: Auto-lock and auto-disconnect settings are configured per connection in the connection settings modal.

Environment Variables

Variable	Description	Default	Required
`WEBSSH_USERS`	Comma-separated user:pass pairs	`admin:admin`	No
`JWT_SECRET`	Secret for token signing	Auto-generated	Recommended
`MAX_UPLOAD_SIZE`	Max file upload (e.g., `10M`, `1G`)	`100M`	No
`RECORDING_ENABLED`	Enable session recording	`true`	No
`RECORDING_RETENTION_DAYS`	Days to keep recordings	`30`	No
`TZ`	Timezone	`UTC`	No

Architecture

This container uses Caddy as a reverse proxy to route traffic:

Port 8080 - Main entry point
/ws → WebSocket SSH server
/api/* → HTTP API (login, verify, SFTP operations)
Everything else → Static files (UI)

Internal services (not exposed):

WebSocket SSH: port 8081
HTTP API: port 8082
WebSocket SFTP: port 8083

Reverse Proxy Setup

Caddy

your-domain.com {
    reverse_proxy localhost:8080
}

Docker Compose

services:
  webssh:
    image: danaildr/webssh:latest
    container_name: webssh
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - WEBSSH_USERS=user1:pass1,user2:pass2
      - JWT_SECRET=your-secret-key-here
      - MAX_UPLOAD_SIZE=100M

Security Notes

⚠️ Important for Production:

Change default credentials - Set strong passwords via WEBSSH_USERS
Set a strong JWT_SECRET - Use at least 32 random characters
Use HTTPS - Configure reverse proxy with SSL/TLS (container handles HTTP internally)
SSH host keys - Uses AutoAddPolicy() by default; configure strict host key checking for production
Session recordings - Stored in /data/recordings/ with metadata in SQLite database
File uploads - Limited by MAX_UPLOAD_SIZE (default 100MB)
Volumes - Mount /data for persistent storage of credentials and recordings

API

POST /api/login - Authenticate and get JWT token
POST /api/verify - Verify token validity
GET /api/connections - List saved connections
POST /api/connections - Save a new connection
GET /api/config - Get server configuration
WebSocket: /ws?token=<JWT> - SSH terminal connection

Source

https://github.com/danaildr/web-ssh

4.9 KiB Raw Blame History