Using a remote Docker host?
The loopback quickstart is reachable on that host, not automatically from your laptop. Choose an appropriate remote deployment from the documentation before opening access to other devices.
Self-hosting WebSSH
Your workspace.
Your deployment.
Install WebSSH on a host you control, connect it to your SSH targets and open your instance in a browser. Docker and Docker Compose provide the container path; a source installation is also documented.
What you need
A host for WebSSH, persistent storage for its data and network access from that host to your SSH or SFTP targets. Your browser connects to WebSSH; WebSSH makes the outbound target connections.
- Your browserOpen the WebSSH interface
- Your WebSSH hostAccounts, sessions and stored data
- Your SSH / SFTP targetsRemote shells and files
Container images are published for AMD64 and ARM64. A source installation requires Python 3.11 or newer. Persistent remote shells additionally need tmux on the target. Your target account's permissions continue to determine what it can do.
Start small
Try the workspace locally.
The copyable Docker quickstart binds port 5000 to loopback and stores application data in the named webssh_data volume. Open http://localhost:5000 on the Docker host and create the first administrator immediately. The one-time browser bootstrap closes after that account exists.
The multi-line command is formatted for Bash or Zsh. On other shells, use the documented Compose path or adapt line continuation to that shell.
Running a trusted homelab?
The base Compose configuration is intended for evaluation and trusted networks. Keep access restricted to trusted users and review origin, registration and target-network settings. A VPN can provide a private access path.
Follow the complete quickstart · Review configuration options
Remote and Internet-facing access
Use the production deployment path.
The production overlay validates a stricter configuration. Use it with an HTTPS reverse proxy and keep the backend on loopback or a private network. The proxy must support WebSocket upgrades for terminal connections.
- Prepare the host and public origin. Set up DNS, a trusted TLS certificate and a maintained reverse proxy. Use Docker Compose 2.24.4 or newer for the production overlay.
- Combine the base and production Compose files. Set the exact HTTPS origin and the correct number of trusted proxy layers. Review the effective configuration before starting.
- Create the administrator on the trusted host. Production disables browser bootstrap and public registration. Use the documented administrator command.
- Verify access and recovery. Check HTTPS, readiness, cookies, origin restrictions, target-network policy and a recoverable backup before admitting users.
Follow the production deployment guide · Reverse proxy and subfolder examples
Operate it over time
Keep data and recovery under your control.
Persistent storage
The data directory contains the database, per-user settings, connections, notes, host trust and encrypted private keys. Container installations persist an automatically generated application secret in the data volume. If you supply an external SECRET_KEY, preserve it separately; it is not copied into that volume. Keep both the data volume and the required secret across container replacement and recovery.
Backups and restore
Native backup and restore use maintenance mode and explicit confirmation. Backups can contain sensitive data and the application secret, so protect them separately and test restoration.
Updates and rollback
Read release notes, record your current image and take a backup before updating. For repeatable deployments, pin a reviewed release tag or digest instead of relying on a moving latest tag.
Capacity and health
WebSSH uses one application worker with bounded threads and resource quotas. Health and readiness checks support operations. Adding extra application workers is not a supported scaling method.
Data storage · Backup and restore · Upgrades and rollback · Health checks
Know the boundaries before you connect.
Understand credentials, host trust and the responsibilities of the operator.