webssh/docker-hub-overview.md

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 MAX_UPLOAD_SIZE=100M \
  --name webssh \
  --restart unless-stopped \
  danaildr/webssh:latest

Then open http://localhost:8080 in your browser.
On first start, create the administrator account in the browser. Use a password with at least 12 characters.

With Persistent Data & Auto-Lock

docker run -d \
  -p 8080:8080 \
  -v webssh_data:/data \
  -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

For a one-time import of legacy accounts, optionally set WEBSSH_USERS=user1:pass1,user2:pass2. The first imported user becomes an administrator, other accounts have the user role, and all imported users must change their password at first login. Administrators can create and delete users from the application. To reset an account password in a running container, use docker exec -it webssh password-reset.

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

Environment Variables

Variable	Description	Default	Required
WEBSSH_USERS	Optional one-time import of legacy user:pass pairs; imported accounts must change their passwords	None	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:
      # Optional one-time import of legacy users:
      - WEBSSH_USERS=user1:pass1,user2:pass2
      - JWT_SECRET=your-secret-key-here
      - MAX_UPLOAD_SIZE=100M

Security Notes

⚠️ Important for Production:

• Create strong user passwords - The first user is created during setup; imported users are prompted to replace legacy passwords
• 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

Tags

• latest - Most recent stable build
• 0.4.0 - Version-specific tag (Grouped recordings + Bulk operations + Multi-arch support)
• 0.3.1 - Previous version

Multi-arch: All tags support both linux/amd64 and linux/arm64.