WebSSH
Docker app from webssh's Repository
WebSSH is a self-hosted, multi-user SSH and SFTP client in the browser: terminals with optional persistent tmux sessions, a file workspace, saved hosts, jump hosts and SOCKS5…
Requirements
Overview
Readme
View on GitHubInstall on Unraid
WebSSH ships an Unraid template next to its source code:
unraid/webssh.xml.
It runs the official image ghcr.io/bifrost0x/webssh:latest with the same
homelab settings as the supplied docker-compose.yml. A test keeps both in
sync, so a new port, path or setting always reaches the template in the same
change.
Before you install
WebSSH is an SSH gateway. Anyone who can sign in can reach every SSH target that WebSSH's network allows. The template uses the homelab profile for a trusted LAN: plain HTTP, any origin you use on the LAN, and browser registration for the first account.
Do not forward the WebUI port to the Internet. For remote access use a VPN, or follow Production Deployment for HTTPS through a reverse proxy with the production profile.
The first account created in the browser becomes the administrator. Open the WebUI and create it right after installation. To close that window entirely, add the variable
BOOTSTRAP_REGISTRATION_ENABLEDwith the valuefalsebefore you apply the template, then create the administrator from the Unraid terminal:docker exec -it WebSSH /app/entrypoint.sh flask --app start:app create-admin --username admin
Install the template
From Apps, search for WebSSH and select Install.
Until the Community Apps listing is available, copy the template into Unraid's user templates from the Unraid terminal:
curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-WebSSH.xml \
https://raw.githubusercontent.com/bifrost0x/webssh/main/unraid/webssh.xml
Then open Docker > Add Container and select the WebSSH template.
Review the settings and select Apply:
| Setting | Default | Notes |
|---|---|---|
| WebUI port | 5000 |
Host port of the web interface. |
| Data | /mnt/user/appdata/webssh/data |
Database, generated application secret, encrypted keys and user files. |
| Recovery | /mnt/user/appdata/webssh/recovery |
Durable backup and restore staging. Keep it outside the data folder. |
| Allowed origins | * |
Any address you use on the LAN. Set exact origins such as http://tower:5000 and Allow origin wildcard to false to restrict it. |
| Trusted proxies | 0 |
Number of reverse proxies in front of WebSSH. |
| Secure cookies | false |
Set true when WebSSH is only reached over HTTPS. |
Advanced settings mirror the remaining homelab variables. The template sets no secret: WebSSH generates its application secret on first start and keeps it in the data folder. All other settings are described in the Configuration Reference; add them as variables in the template when you need them.
The template icon is assets/webssh-icon.png from the repository.
First start
Open the WebUI from the Docker tab. A fresh instance redirects to the registration page; create the administrator account there. Then add SSH hosts as described in SSH Connections and Host Keys.
Container user and appdata permissions
The template sets Extra Parameters to
--user 99:100 --cap-drop ALL --security-opt no-new-privileges:true, so
WebSSH runs as nobody:users, never as root, without Linux capabilities and
without privilege gains through setuid programs. When you apply a template,
Unraid creates missing appdata folders and gives them to nobody:users, so the
first start can write them. WebSSH then restricts the folders to mode 0700.
Keep these parameters. Without --user, the image runs as its built-in user
(UID 1000), which cannot write the folders Unraid created.
If the log shows must be owned and writable by the container user 99:100,
the folders belong to another user, for example because they were created from
the terminal as root or restored from another system. Stop the container, then
run:
chown -R 99:100 /mnt/user/appdata/webssh
Moving an existing Docker Compose installation
Compose installations store data as the image's built-in user (UID 1000).
Copy the data and recovery volumes into the appdata folders while the old
container is stopped, then run the chown command above. Keep the same data
folder, because it contains the application secret that decrypts stored keys.
Keep appdata private
The data folder contains the application secret next to the encrypted SSH keys and passwords. Anyone who can read both can decrypt them.
99:100 is the identity most Unraid containers and guest access to shares use.
Mode 0700 keeps other users out, but not other processes running as 99:100:
a container with that identity that maps /mnt/user or /mnt/user/appdata can
read WebSSH's data.
- Do not map
/mnt/useror theappdatashare into other containers that run as99:100, or run WebSSH as a dedicated user instead (see below). - Do not export the
appdatashare over SMB or NFS. - Leave the WebSSH appdata folder out of permission-reset tools such as New Permissions.
- Back up the data and recovery folders encrypted and off the server.
- Use the built-in backup described in Backup, Restore, and Secret Rotation before major updates.
Run as a dedicated user
A numeric ID that no other container or Unraid account uses isolates WebSSH's
data from them. Unraid accounts usually start at 1000, so pick a higher unused
number, for example 10000. Stop the container, give the folders to that ID
and change only the --user value in Extra Parameters:
chown -R 10000:10000 /mnt/user/appdata/webssh
--user 10000:10000 --cap-drop ALL --security-opt no-new-privileges:true
Do not use 0:0. If you later change the folder paths, create and chown the
new folders before the first start, because Unraid gives new folders to
nobody:users.
Updates
Unraid's update pulls the newest latest image and recreates the container
with the same appdata folders. Create a verified backup first. For controlled
updates, set Repository to a published version tag from the
releases instead of latest
and change it deliberately. Read the release notes before upgrading across
versions; see
Upgrading, Rollback, and FAQ.
WebSSH's graceful shutdown can take up to 30 seconds. Unraid stops containers with its own timeout, which may be shorter; an early stop ends open SSH sessions and transfers.
Remove or reinstall
Removing the container keeps the appdata folders. Reinstalling with the same
paths reuses the data, accounts and application secret. To remove everything,
create a backup if you may need the data later, then delete
/mnt/user/appdata/webssh.
Troubleshooting
- Container stops right after start: read the container log in the Docker tab. Permission errors name the required owner; see above.
- Unhealthy: see Health Checks and Troubleshooting.
- Cannot reach an SSH host: the container uses Unraid's bridge network. Hosts must be reachable from Docker containers on the server.
Ask Unraid questions in the support thread and report bugs as GitHub issues.
Media gallery
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/bifrost0x/webssh:latestRuntime arguments
- Web UI
http://[IP]:[PORT:5000]/- Network
bridge- Shell
bash- Privileged
- false
- Extra Params
--user 99:100 --cap-drop ALL --security-opt no-new-privileges:true
Template configuration
HTTP port of the web interface. Keep it on your LAN.
- Target
- 5000
- Default
- 5000
- Value
- 5000
Database, generated application secret, encrypted keys and user files. Back it up and keep it private.
- Target
- /app/data
- Default
- /mnt/user/appdata/webssh/data
- Value
- /mnt/user/appdata/webssh/data
Durable backup and restore staging, including rollback copies. Keep it outside the data folder.
- Target
- /app/recovery
- Default
- /mnt/user/appdata/webssh/recovery
- Value
- /mnt/user/appdata/webssh/recovery
homelab keeps HTTP and private-network compatibility for a trusted LAN. Use production only behind HTTPS as documented.
- Target
- DEPLOYMENT_PROFILE
- Default
- homelab
- Value
- homelab
Origins allowed to open WebSSH. '*' accepts any address you use on the LAN; set exact origins such as http://tower:5000 to restrict it.
- Target
- CORS_ORIGINS
- Default
- *
- Value
- *
Permits '*' in Allowed origins for the homelab profile. Set false when you list exact origins.
- Target
- ALLOW_CORS_WILDCARD
- Default
- true
- Value
- true
Number of reverse proxies in front of WebSSH. 0 for direct LAN access.
- Target
- TRUSTED_PROXIES
- Default
- 0
- Value
- 0
Set true when WebSSH is only reached over HTTPS.
- Target
- SESSION_COOKIE_SECURE
- Default
- false
- Value
- false
Name prefix for persistent tmux sessions on remote hosts.
- Target
- TMUX_SESSION_PREFIX
- Default
- webssh
- Value
- webssh
Deployment-level switch for authenticator-app MFA. Administrators still decide in the interface whether users can enroll.
- Target
- TOTP_ENABLED
- Default
- true
- Value
- true
Only for OpenID Connect: signed amr values your provider documents as MFA. Leave empty otherwise.
- Target
- OIDC_MFA_AMR_VALUES
Only for OpenID Connect: signed acr values your provider documents as MFA. Leave empty otherwise.
- Target
- OIDC_MFA_ACR_VALUES
Only for OpenID Connect: signed amr values for phishing-resistant MFA. Leave empty otherwise.
- Target
- OIDC_PHISHING_RESISTANT_AMR_VALUES
Only for OpenID Connect: signed acr values for phishing-resistant MFA. Leave empty otherwise.
- Target
- OIDC_PHISHING_RESISTANT_ACR_VALUES
Only for OpenID Connect: acr values requested for step-up authentication. Leave empty otherwise.
- Target
- OIDC_STEP_UP_ACR_VALUES
Seconds a step-up authentication stays valid for sensitive administrator actions.
- Target
- STEP_UP_MAX_AGE_SECONDS
- Default
- 300
- Value
- 300
Container path for backup and restore staging. Keep the default so it uses the Recovery folder.
- Target
- BACKUP_TEMP_DIR
- Default
- /app/recovery
- Value
- /app/recovery
Confirms that the Recovery folder is persistent storage, which online restore requires.
- Target
- BACKUP_RECOVERY_DURABLE
- Default
- true
- Value
- true