danaildr/webssh repository overview

⁠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, linux/arm/v7 and linux/arm64
• Lightweight - Alpine-based images with nginx 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

⁠Architecture

This container uses nginx 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
}

⁠Nginx

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

⁠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

⁠Tags

• latest - Most recent stable build
• 0.3.1 - Version-specific tag (update session records view)
• 0.3.0 - Previous version first version support arm/v7 ( support linux/amd64, linux/arm64 and linux/arm/v7)
• 0.2.2 - Previous version (only linux/amd64 and linux/arm64)

Multi-arch: All tags support linux/amd64, linux/arm/v7 and linux/arm64.