Web Shell

Secure browser-based terminal built on our Debian base image with ttyd for web terminal access. Includes common DevOps and hosting tools, optional SSH server, and flexible authentication options.

Verify this image

Every build ships a Sigstore-signed SBOM and a full Trivy scan — verify them yourself, no login required:

gh attestation verify oci://ghcr.io/oorabona/web-shell:latest --owner oorabona

Full walkthrough (SBOM payload, Trivy findings, multi-arch manifest inspection, upstream dependency tracking) → https://oorabona.github.io/docker-containers/verify-images/

Quick Start

# Pull the image
docker pull ghcr.io/oorabona/web-shell:latest

# Run with default settings (web terminal on port 7681)
docker run -d --name web-shell -p 7681:7681 ghcr.io/oorabona/web-shell:latest

# Open in browser
# http://localhost:7681

# Run with password and SSH enabled
docker run -d --name web-shell \
  -p 7681:7681 -p 2222:2222 \
  -e SHELL_PASSWORD=mysecretpass \
  -e ENABLE_SSH=true \
  ghcr.io/oorabona/web-shell:latest

Build

# Build with latest upstream ttyd version
./make build web-shell

# Build with specific ttyd version
./make build web-shell 1.7.7

Build Args

Environment Variables

Ports

Included Tools

Authentication

No Authentication (default)

Anyone with network access can use the terminal. Suitable for local development or behind a trusted reverse proxy.

Basic Auth (ttyd built-in)

docker run -d -p 7681:7681 \
  -e TTYD_CREDENTIAL="admin:secretpass" \
  ghcr.io/oorabona/web-shell:latest

TLS Encryption

docker run -d -p 7681:7681 \
  -v /path/to/cert.pem:/certs/cert.pem:ro \
  -v /path/to/key.pem:/certs/key.pem:ro \
  -e TTYD_SSL_CERT=/certs/cert.pem \
  -e TTYD_SSL_KEY=/certs/key.pem \
  ghcr.io/oorabona/web-shell:latest

Reverse Proxy Auth Header

For integration with authentication proxies (OAuth2 Proxy, Authelia, etc.):

docker run -d -p 7681:7681 \
  -e TTYD_AUTH_HEADER="X-Forwarded-User" \
  ghcr.io/oorabona/web-shell:latest

SSH Access

docker run -d -p 7681:7681 -p 2222:2222 \
  -e ENABLE_SSH=true \
  -e SSH_PUBLIC_KEY="ssh-ed25519 AAAA... user@host" \
  ghcr.io/oorabona/web-shell:latest

# Connect via SSH
ssh -p 2222 debian@localhost

Health Check

Built-in health check via ttyd token endpoint:

GET http://localhost:7681/token → {"token": "..."}

Hosting Use Case

Web Shell is designed as a building block for web hosting platforms, providing browser-based terminal access to container environments. Combined with other containers from this project:

┌──────────────────────────────────────────────────────────┐
│  Client Browser                                          │
│  ┌───────────┐  ┌────────────┐  ┌──────────────────┐    │
│  │ Web App   │  │ phpMyAdmin │  │ Web Terminal      │    │
│  │ :80/:443  │  │ :8080      │  │ :7681 (ttyd)     │    │
│  └─────┬─────┘  └─────┬──────┘  └──────┬───────────┘    │
└────────┼───────────────┼────────────────┼────────────────┘
         │               │                │
┌────────┼───────────────┼────────────────┼────────────────┐
│  ┌─────▼─────┐  ┌──────▼─────┐  ┌──────▼───────────┐    │
│  │ OpenResty │  │ PHP-FPM    │  │ Web Shell         │    │
│  │ (proxy)   │  │ WordPress  │  │ (tools + shell)   │    │
│  └───────────┘  └────────────┘  └──────────────────┘    │
│  ┌───────────┐  ┌────────────┐                           │
│  │ PostgreSQL│  │ Vector     │                           │
│  │ (database)│  │ (logs)     │                           │
│  └───────────┘  └────────────┘                           │
│  Docker Host                                             │
└──────────────────────────────────────────────────────────┘

Security Considerations

• Runs as root for chpasswd and sshd, but ttyd spawns shells as the configured SHELL_USER
• No default password — set SHELL_PASSWORD at runtime (account is locked without it)
• SSH listens on port 2222 (non-standard) with root login disabled
• For production: use TTYD_CREDENTIAL or place behind an auth reverse proxy
• Mount TLS certificates for encrypted connections
• The --writable flag enables terminal input — remove for read-only sessions

Dependencies

Links

• ttyd GitHub
• ttyd Wiki
• WebSocket Terminal Protocol
• Debian Base Image