WebSSH - Help

🌟 Key Features

🔐 Secure Authentication

JWT-based login with configurable session timeout and encrypted storage of passwords and SSH keys.

🌐 Multiple Connections

Connect to multiple SSH servers simultaneously with easy switching between them.

📁 SFTP File Manager

Full-featured file manager with drag & drop upload, download, and file operations.

💾 Persistent Data

Encrypted storage of credentials across container restarts.

📊 Upload Limits

Configurable maximum file size (supports formats like "30M", "100M", "1G").

🎥 Session Recording

Automatic recording of SSH sessions in asciinema format with playback and configurable retention period.

🎨 Modern Interface

Responsive design with dark/light theme and intuitive controls.

🚀 Quick Start

Open your browser and go to http://localhost:8080
Login with username and password (default: admin/admin)
Create a connection by clicking "+ New Connection" and entering SSH server details
Connect by clicking on the created connection
Open terminal and start working with the remote server
Use SFTP for file operations by clicking the "Files" tab

🎥 Session Recordings

All SSH sessions are automatically recorded in asciinema format. To view recordings:

Click "Recordings" button in the left sidebar
Browse the list of recorded sessions (shows connection name, date, and duration)
Click ▶ Play to replay the recording in the embedded player
Download the recording as .cast.gz file for local storage
Delete old recordings to free up space

Recordings are kept for a configurable period (default 30 days) and automatically deleted after that.

⌨️ Keyboard Shortcuts

🖥️ Terminal:

Copy Ctrl+C

Paste Ctrl+V

New Terminal Ctrl+T

Close Tab Ctrl+W

📁 SFTP File Manager:

Refresh F5

Delete Delete

Rename F2

Upload Ctrl+U

🔧 Configuration

MAX_UPLOAD_SIZE: Maximum file size (supports formats):

"50M" - 50 megabytes
"100M" - 100 megabytes
"1G" - 1 gigabyte
"500K" - 500 kilobytes

WEBSSH_USERS: Users in format username:password,username2:password2

JWT_SECRET: Secret key for JWT tokens (auto-generated if not set)

RECORDING_ENABLED: Enable/disable session recording (true or false)

RECORDING_RETENTION_DAYS: Number of days to keep recordings (default: 30)

🔒 Auto-Lock & Auto-Disconnect

WebSSH can automatically lock sessions after a period of inactivity and require your WebSSH password to unlock. Sessions can also be automatically disconnected after a longer period.

Lock after: Period of inactivity before locking (5, 15, 30, 60 minutes)
Disconnect after: Period of inactivity before disconnecting (30, 60 minutes, or never)
Configuration: Set per connection in the connection settings
Security: Lock requires WebSSH password only (not SSH password)

🛠️ Troubleshooting

⚠️ Common Issues:

Connection refused: Check if SSH server is running and port is open
Authentication failed: Check username and password
File too large: Increase MAX_UPLOAD_SIZE in docker-compose.yml
401 Unauthorized: Refresh the page and login again
Slow connection: Check internet connection and network settings

🔒 Security

Encryption: All passwords and SSH keys are encrypted with AES-128 (Fernet).

JWT Tokens: Sessions are managed with JWT tokens with configurable timeout.

Docker Isolation: The application runs in an isolated Docker environment.

HTTPS: Recommended to use HTTPS in production environment.

🔐 WebSSH