# WebSSH - Browser-based SSH Client

[![Docker Pulls](https://img.shields.io/docker/pulls/danaildr/webssh)](https://hub.docker.com/r/danaildr/webssh)
[![Docker Image Size](https://img.shields.io/docker/image-size/danaildr/webssh/latest)](https://hub.docker.com/r/danaildr/webssh)

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
```bash
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
```bash
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
```caddyfile
your-domain.com {
    reverse_proxy localhost:8080
}
```

## Docker Compose

```yaml
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

## 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`.