WebSSH

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

Keep the appdata folders private. Their contents include the application secret and encrypted SSH keys.
Overview
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 routes, encrypted keys, host-key verification, commands, backup and restore. Security: WebSSH is an SSH gateway. Anyone who can sign in can reach the SSH targets its network allows. This template uses the homelab profile for a trusted LAN. Do not publish it to the internet; for remote access use a VPN, or a reverse proxy with HTTPS and the production profile described in the production deployment guide: https://github.com/bifrost0x/webssh/blob/main/docs/wiki/Production-Deployment.md First start: the first account created in the browser becomes the administrator. Open the WebUI and create it right after installation, before anyone else can reach the instance. The container runs as nobody:users (99:100) without Linux capabilities, never as root. Unraid creates the appdata folders for that user on installation. Other containers running as 99:100 with access to the appdata share can read WebSSH's data; the install guide explains how to isolate it. The template sets no secret; WebSSH generates its application secret on first start and keeps it in the data folder.

Install 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_ENABLED with the value false before 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/user or the appdata share into other containers that run as 99:100, or run WebSSH as a dedicated user instead (see below).
  • Do not export the appdata share 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

Links

Details

Repository
ghcr.io/bifrost0x/webssh:latest
Last Updated2026-11-19
First Seen2026-11-19

Runtime 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

WebUI portPorttcp

HTTP port of the web interface. Keep it on your LAN.

Target
5000
Default
5000
Value
5000
DataPathrw

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
RecoveryPathrw

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
Deployment profileVariable

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
Allowed originsVariable

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
*
Allow origin wildcardVariable

Permits '*' in Allowed origins for the homelab profile. Set false when you list exact origins.

Target
ALLOW_CORS_WILDCARD
Default
true
Value
true
Trusted proxiesVariable

Number of reverse proxies in front of WebSSH. 0 for direct LAN access.

Target
TRUSTED_PROXIES
Default
0
Value
0
Secure cookiesVariable

Set true when WebSSH is only reached over HTTPS.

Target
SESSION_COOKIE_SECURE
Default
false
Value
false
tmux session prefixVariable

Name prefix for persistent tmux sessions on remote hosts.

Target
TMUX_SESSION_PREFIX
Default
webssh
Value
webssh
TOTP availableVariable

Deployment-level switch for authenticator-app MFA. Administrators still decide in the interface whether users can enroll.

Target
TOTP_ENABLED
Default
true
Value
true
OIDC MFA amr valuesVariable

Only for OpenID Connect: signed amr values your provider documents as MFA. Leave empty otherwise.

Target
OIDC_MFA_AMR_VALUES
OIDC MFA acr valuesVariable

Only for OpenID Connect: signed acr values your provider documents as MFA. Leave empty otherwise.

Target
OIDC_MFA_ACR_VALUES
OIDC phishing-resistant amr valuesVariable

Only for OpenID Connect: signed amr values for phishing-resistant MFA. Leave empty otherwise.

Target
OIDC_PHISHING_RESISTANT_AMR_VALUES
OIDC phishing-resistant acr valuesVariable

Only for OpenID Connect: signed acr values for phishing-resistant MFA. Leave empty otherwise.

Target
OIDC_PHISHING_RESISTANT_ACR_VALUES
OIDC step-up acr valuesVariable

Only for OpenID Connect: acr values requested for step-up authentication. Leave empty otherwise.

Target
OIDC_STEP_UP_ACR_VALUES
Step-up maximum ageVariable

Seconds a step-up authentication stays valid for sensitive administrator actions.

Target
STEP_UP_MAX_AGE_SECONDS
Default
300
Value
300
Backup staging directoryVariable

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
Durable recoveryVariable

Confirms that the Recovery folder is persistent storage, which online restore requires.

Target
BACKUP_RECOVERY_DURABLE
Default
true
Value
true