WebSSH 2.1.0

WebSSH 2.1.0

WebSSH 2.1.0 adds secure, opt-in SMB file sources to the existing file workspace and delivers a focused set of authentication, File Manager, interface, deployment, and documentation improvements since WebSSH 2.0.

Highlights

• Added encrypted SMB 3.1.1 sources to the File Manager
• Added uploads, downloads, editing, recursive operations, and SFTP ↔ SMB transfers
• Added reusable per-user SMB share definitions without storing passwords
• Improved File Manager lifecycle, Quick Connect, modal controls, themes, and mobile behavior
• Fixed stale remember-cookie login loops
• Added a comprehensive versioned Wiki with automatic publication

SMB File Sources

SMB support is disabled by default and must be enabled explicitly by the operator.

• Requires an exact SMB_ALLOWED_TARGETS hostname/IP allowlist
• Uses fixed TCP port 445 and requires SMB 3.1.1, signing, encryption, and secure negotiation
• Stores only non-secret share metadata; SMB passwords are never persisted
• Revalidates user ownership and source capabilities at operation boundaries
• Confines paths to the selected share and rejects reparse traversal and share-root mutations
• Uses atomic editor replacement and fails closed when a safe replacement is unavailable
• Applies bounded quotas, cancellation, connection holds, and canonical lock ordering to transfers
• Records credential-free host, share, operation, and result metadata in the audit log
• Provides a responsive connection flow aligned with Quick Connect and SFTP

To enable SMB:

SMB_ENABLED=true
SMB_ALLOWED_TARGETS=nas.example,10.0.0.8

Restart WebSSH after changing the environment. Wildcards, ports, and paths are not accepted in SMB_ALLOWED_TARGETS.

Reliability and Interface Improvements

• Fixed embedded SFTP restoration after closing the full File Manager
• Corrected Escape handling so source dialogs close before the File Manager
• Fixed Paper Ops text contrast and shared theme aliases
• Removed the duplicate Quick Connect action and routed remaining launchers consistently
• Restored Material Icons rendering for modal close controls
• Fixed stale Flask-Login remember cookies that could cause repeated login redirects
• Allowed fresh passkey-authenticated sessions to authorize initial TOTP enrollment
• Streamlined Docker Compose configuration without changing resolved defaults

Documentation and Operations

• Rebuilt the README with a current product tour, quick start, and security overview
• Added a comprehensive versioned Wiki covering deployment, authentication, SSH/SFTP workflows, administration, backup/restore, and troubleshooting
• Added current architecture and security diagrams
• Added a hardened workflow that publishes the versioned documentation to the GitHub Wiki
• Updated locked Python dependencies and dependency-policy checks

Security and Validation

The release candidate at 81ecfedc3c550eb3970ef43238bacceb06cc2851 passed:

• 2,081 Python tests on Python 3.11 and Python 3.14
• 306 JavaScript unit tests
• 91 Playwright browser tests
• Disposable encrypted SMB integration checks
• 27 disposable OpenSSH / Paramiko integration tests
• Redis 7 and Redis 8 rate-limiter tests
• Dependency-lock and vendored-asset checks
• CodeQL analysis for Python, JavaScript/TypeScript, and GitHub Actions
• AMD64 and ARM64 container builds
• SPDX SBOM generation and Trivy scans for fixable High/Critical findings

Upgrade

Existing WebSSH 2.0 installations can upgrade using the normal container update process. Persistent data formats remain compatible and SMB stays disabled unless explicitly configured.

Backing up the WebSSH data volume before upgrading is recommended.

---

Full Changelog: v2.0.0...v2.1.0

WebSSH 2.0

WebSSH 2.0

WebSSH 2.0 is a major update focused on security, authentication assurance, session management, and a completely redesigned responsive workspace.

Highlights

• Completely redesigned responsive WebSSH workspace
• New Security Center and Admin Center experience
• Improved mobile and tablet support
• Context-based workspace for Files, Commands, Diagnostics, and Notes
• Per-session SFTP and diagnostics integration
• Improved split-pane and multi-session workflows
• Major authentication and MFA improvements
• Extensive security hardening across authentication, sessions, administration, and SSH

Authentication & Security

• Added optional TOTP authenticator-app MFA
• Added Passkey MFA support across supported authentication flows
• Improved LDAP / Active Directory authentication
• Enhanced OpenID Connect authentication and assurance handling
• Added administrator-controlled authentication feature gates
• Added action-bound administrator step-up authentication
• Added single-use, session-bound, action-bound, and target-bound authorization grants
• Improved authentication assurance tracking
• Restricted recovery codes to second-factor recovery
• Hardened factor enrollment and recovery flows
• Improved handling of parallel authentication sessions and browser tabs
• Added revalidation of authenticated Socket.IO sessions
• Improved redaction of sensitive audit information
• Improved SSH host-key error handling without exposing backend internals
• Authentication capabilities now fail closed when required deployment configuration is unavailable

MFA & Account Security

• Optional TOTP enrollment with encrypted authenticator secrets
• TOTP replay protection
• One-time recovery codes
• Safe MFA replacement and recovery flows
• Passkeys and TOTP can be used for MFA-enabled accounts
• Recovery codes can only be used after successful primary authentication
• Recovered sessions are restricted until account security has been repaired
• MFA remains optional per account unless enabled by the user and permitted by the deployment

Administrator Security

• Added administrator security feature controls
• Sensitive administrative actions now require fresh authentication assurance
• Administrator step-up grants are short-lived and single-use
• Step-up authorization is bound to the current session, action, and target
• Authentication capabilities remain constrained by deployment configuration
• Security policy changes no longer unexpectedly terminate active browser or SSH sessions
• Improved warnings for configuration changes that could affect future administrator access

OpenID Connect

• Improved OIDC callback implementation
• Added explicit authentication assurance validation
• Added configurable MFA and phishing-resistant amr / acr values
• Added provider-driven OIDC step-up authentication
• OIDC assurance is only trusted when signed claims match explicitly configured values
• Missing or unknown assurance claims remain basic assurance
• Stable issuer and subject identifiers continue to be used for account linking
• OIDC accounts are never automatically linked by email address

LDAP / Active Directory

• Improved LDAP and LDAPS authentication flows
• Added MFA support for LDAP-authenticated accounts
• Sensitive account operations perform fresh directory verification
• LDAP credentials remain server-side
• Deployment configuration remains the hard capability boundary for LDAP authentication

Workspace & Sessions

• Completely redesigned responsive desktop, tablet, and mobile workspace
• Connection sessions are now separated from contextual tools
• Files, Commands, Diagnostics, and Notes are available through the context workspace
• Embedded SFTP is bound to the active SSH session
• Diagnostics are bound to the active SSH session
• Added expandable diagnostics overlay
• Added resizable desktop context panel
• Improved behavior when resizing the application
• Improved handling of unavailable session capabilities
• Added configurable disconnect behavior
• Persistent tmux sessions remain reconnectable
• Improved session capability detection
• Improved active-session command handling
• Improved session lifecycle behavior

SFTP & Host Management

• Improved per-session SFTP integration
• Improved SFTP capability detection
• Hardened SFTP probe lifecycle
• Active SFTP panels are preserved correctly during resize
• Improved Hosts management
• Existing authentication, ownership, host-key, network-policy, transfer, and SFTP security boundaries are preserved

UI / UX

• Redesigned authentication pages
• Redesigned Security Center
• Redesigned Admin Center
• Improved application navigation
• Improved responsive scaling
• Improved mobile account menu
• Improved footer visibility
• Improved theme compatibility
• Updated translations
• Improved safe UI defaults
• Existing users retain their previous close-confirmation behavior
• New accounts receive the updated default behavior

Deployment & Configuration

• Updated Docker and homelab configuration documentation
• Added TOTP deployment configuration
• Added OIDC authentication-assurance configuration
• Added administrator step-up configuration
• Improved reverse-proxy documentation
• Added proxy-neutral Apache reverse-proxy documentation
• Existing stored preferences remain compatible
• Configuration and schema changes are additive
• Explicit existing user preferences continue to take precedence
• Authentication features now distinguish between deployment capability, runtime readiness, and administrator activation

Security Validation

WebSSH 2.0 received extensive security and regression testing before release:

• 1,806 Python tests passed
• Python 3.11 validated
• Python 3.14 validated
• 283 JavaScript unit tests passed
• 79 Playwright browser tests passed
• ESLint passed
• 10 vendored frontend assets verified
• Dependency lock validation passed
• 27 disposable OpenSSH / Paramiko integration tests passed
• Production Python 3.14 container image built successfully
• Independent security and regression review completed with no remaining Critical or Important findings

Upgrade

Existing Docker and homelab installations can upgrade using the normal container update process.

Review the updated authentication and security configuration when enabling TOTP, Passkeys, LDAP, OIDC, or administrator step-up functionality.

As always, backing up persistent WebSSH data before a major-version upgrade is recommended.

---

Full Changelog: Changes included in WebSSH 2.0 are based on the current main branch at the time of release.

WebSSH v1.3.0

WebSSH v1.3.0

WebSSH v1.3.0 makes recurring administration work faster and gives saved
connections a more predictable, professional management experience.

Highlights

Commands for the active session

• Search saved commands and resolved command sets directly from the active
  terminal pane
• Insert the selected command visibly into the connected session without
  executing it automatically
• Keep multiline, empty, unresolved, stale, or disconnected targets unavailable
  instead of guessing or sending unsafe input
• Preserve terminal focus and clearly identify the target session after insertion

Reliable saved-host organization

• Reorder profiles precisely within favorites, named groups, and ungrouped hosts
• Move profiles between groups with persisted per-group ordering
• Collapse groups without losing search visibility
• Confirm before moving the final profile out of a group and implicitly removing
  that group
• Reject stale drag-and-drop operations and return authoritative server state
  when another update won the race

Safer SSH key maintenance

• Replace a stored private key in place without rebuilding profiles that already
  reference it
• Preserve the replacement draft after a failed attempt so the operation can be
  retried
• Keep key validation, encryption, ownership checks, and safe response summaries
  on the existing server-side path

Security, compatibility, and maintenance

• Updated and hash-locked Python dependencies, including Paramiko 5 and current
  cryptography, bcrypt, Gunicorn, Socket.IO, WebAuthn, OIDC, and Redis contracts
• Removed packaging tools from the final runtime image after dependency
  installation
• Corrected Socket.IO source filtering for browser-side error reporting
• Narrowed SSH key decryption exception handling so process-level interrupts are
  no longer swallowed
• Expanded regression coverage across profile ordering, key replacement,
  command insertion, browser behavior, and Socket.IO contracts

Upgrade

docker compose pull
docker compose up -d

Existing persistent data remains under the configured DATA_DIR or Docker
volume. Profile ordering is added compatibly; existing profiles retain their
stable legacy order until an explicit move persists the new order.

Full changelog: v1.2.0...v1.3.0

WebSSH v1.2.0

WebSSH v1.2.0

WebSSH v1.2.0 turns the terminal view into a more complete server workspace. The active Linux session now combines SSH, SFTP, live telemetry, notes, and an expanded diagnostics view without sending monitoring data to an external service.

Highlights

Active-session monitoring

• Live CPU, memory, disk, load, uptime, process-count, and network-throughput telemetry for the selected Linux session
• An 80%-width diagnostics drawer with resource cards, session-local history, pressure and network charts, and top CPU and memory processes
• Bounded systemd service and Docker container inventories with search, state filters, truncation indicators, stale-cache handling, and explicit permission notices
• Clipboard-only start, stop, and restart helpers for allowlisted systemd units. WebSSH copies the command with visible confirmation but never executes the service action
• Missing tools and ordinary collection errors stay out of the interface; permission restrictions remain visible and scoped to the affected section

Focused server workspace

• Embedded single-session SFTP browser beside the terminal
• Automatic SFTP opening for one connected session on wide desktop layouts, while respecting manual close
• Live Linux telemetry and per-session notes in the workspace sidebar
• Refreshed deterministic product screenshots for the workspace and diagnostics view

Faster navigation and saved-host organization

• Unified access to saved hosts, jump hosts, SSH keys, commands, and preferences
• Account-menu workspace pulse for active sessions and occupied panes
• Saved-host favorites and named groups
• Ctrl+K navigation across saved hosts, active sessions, favorites, and application actions

Security and maintenance

• Fixed and hardened dependency locks with cross-platform verification
• Automated, credential-isolated Dependabot refreshes for vendored browser assets
• Updated Python and Docker test dependencies
• Diagnostics requests remain authenticated, session-owned, rate-limited, correlated, size-bounded, timeout-bounded, and read-only
• Remote inventory values are strictly parsed and rendered as text; no external frontend dependency or telemetry endpoint was added

Upgrade

docker compose pull
docker compose up -d

Existing persistent data remains under the configured DATA_DIR or Docker volume.

Full changelog: v1.1.0...v1.2.0

WebSSH v1.1.0

WebSSH v1.1.0

WebSSH v1.1.0 is a substantial security, reliability, identity, and administration update. It adds native web backup and restore, modern authentication options, stronger SSH and storage boundaries, safer transfer handling, and a significantly expanded test and supply-chain baseline.

Highlights

Native web backup and restore

• Create, download, upload, verify, and restore backups directly from Administration > Backup & Restore.
• Create online-consistent snapshots with SQLite's native backup API while WebSSH remains available.
• Protect generated archives with administrator-only, session-bound, one-time downloads and automatic expiry.
• Validate uploaded archives against path traversal, symlinks, duplicate or encrypted members, ZIP bombs, checksum and size mismatches, malformed databases, and unsupported schema versions.
• Restore through maintenance mode with password reauthentication, two explicit confirmations, emergency rollback, session invalidation, and a controlled application restart.
• Preserve verification and restore support for legacy format-v1 archives while new CLI and web archives use format v2 with explicit data-schema compatibility.
• Keep the existing offline CLI backup, verification, restore, and persisted-secret rotation workflows fully supported.

Backup archives contain highly sensitive application data. Store downloaded archives encrypted, off-host, and with access restricted to administrators.

Authentication and account security

• Add username-less discoverable passkey sign-in and a password-protected credential replacement path.
• Add OIDC identity support with explicit administrator linking based on stable issuer and subject identifiers. Accounts are never linked automatically by email address.
• Add recovery-code management, hardened recovery login, bounded WebAuthn challenges, and a dedicated Security interface.
• Make the first account on a fresh standard installation the initial administrator through a one-time atomic bootstrap flow.
• Preserve existing administrator assignments and repair only legacy installations that contain users but no administrator.
• Add administrator audit export, retention controls, completeness metadata, and safer asynchronous security actions.

SSH, SFTP, and persistent-state hardening

• Replace Eventlet with native threaded Socket.IO and background execution while retaining the required single-worker deployment model for process-local SSH state.
• Add per-user SSH host trust, persistent host-key verification, DNS/address pinning, stronger SSRF controls, resource quotas, and bounded Paramiko operations.
• Add explicit transfer lifecycle management, cancellation, bounded upload and download routes, reliable temporary-client cleanup, and safer remote ZIP handling.
• Harden atomic storage, schema validation, corruption handling, migrations, user deletion quarantine, and secret rotation with rollback safeguards.
• Add graceful runtime shutdown, connection cleanup, liveness and readiness endpoints, and persistent-data write checks.
• Upgrade the container runtime to Python 3.14 and refresh the locked Python, JavaScript, and CI dependency stack.

Saved connection workflow

• Launch complete saved connections directly without flashing the Quick Connect dialog.
• Fall back to review only when a password, key, jump-host credential, or authorization decision is still required.
• Upload SSH keys inline while editing a saved connection without losing entered profile data.
• Rename stored keys atomically while preserving key usability after mutation acknowledgements.
• Use consistent Saved Connections and Quick Connect terminology across all six supported languages.
• Improve keyboard accessibility, touch targets, and the 375 px mobile layout.

Operations and supply-chain security

• Add /health and /ready endpoints and use readiness checks for the container healthcheck.
• Add a production Compose overlay and clearer reverse-proxy, secret, identity-provider, backup, and recovery guidance.
• Reproducibly lock Python dependencies with hashes and validate the locks in CI.
• Pin GitHub Actions and container inputs, and add CodeQL, Trivy, dependency, browser, Redis 7/8, SSH integration, and container-threading gates.
• Publish multi-architecture AMD64 and ARM64 images with SBOM and provenance attestations.

Upgrade notes

1. Create and download a verified backup before upgrading. The new native Admin workflow can create an online-consistent backup without stopping WebSSH.

2. Pull the versioned image ghcr.io/bifrost0x/webssh:1.1.0, or update an existing Compose deployment with:

   docker compose pull
   docker compose up -d

3. Wait for the container healthcheck and verify /ready, administrator login, stored keys, a direct terminal connection, and SFTP before returning the service to users.

Built-in database and storage migrations run during startup. Existing users and administrator assignments are preserved, but backups remain mandatory before an upgrade of persistent state.

Custom Python deployments should note that the runtime no longer uses Eventlet. The official container now uses Python 3.14. WebSSH must still run with one application worker because live SSH state remains process-local.

Validation

The release commit passed the complete Python test matrix, JavaScript unit tests, browser E2E scenarios, Redis 7 and 8 checks, SSH integration, container-threading smoke tests, dependency-lock verification, CodeQL, Trivy image scanning, and multi-architecture Docker builds.

Included pull requests

• #60 - Upgrade dependencies and harden multi-user security
• #58 - Update Playwright to 1.62.0
• #64 - Update pinned GitHub Actions
• #63 - Update the Docker runtime to Python 3.14
• #65 - Isolate secret-rotation CLI fixtures
• #69 - Improve saved connection workflows
• #70 - Preserve key usability after mutations
• #71 - Add native Admin backup and restore
• #67 - Update Playwright to 1.62.1
• #66 - Update Graphify to 0.9.31

Full changelog: v1.0.0...v1.1.0

Thank you to everyone who tested WebSSH, reported issues, suggested improvements, or contributed changes.

WebSSH v1.0.0

WebSSH v1.0.0

This is the first official release of WebSSH: a modern, self-hosted browser-based SSH terminal with an integrated SFTP file manager.

WebSSH is designed for homelabs, server administration, and small teams that want convenient browser access without relying on an external service.

Highlights

Terminal

• Up to 10 concurrent SSH sessions
• Tabs and 1, 2, or 4-pane layouts
• Broadcast input across multiple sessions
• Persistent remote sessions through tmux
• Session restoration and manual reconnect
• Saved connection profiles and jump hosts
• Reusable post-connect command sets
• Command palette, terminal search, notes, and transcripts
• Configurable scrollback and multiple terminal themes

SFTP file manager

• Dual-pane file browser
• Drag-and-drop uploads
• Server-to-server transfers
• Transfer queue with conflict handling
• Batch operations
• File previews and log tail mode
• Inline text editor
• Directory downloads as ZIP archives
• Direct SFTP access without opening a terminal

Multi-user administration

• Individual user accounts
• Per-user profiles, SSH keys, commands, and settings
• Administrator panel and user management
• Registration controls
• Structured audit logging
• Six interface languages

Security

• Encrypted SSH key storage
• Per-user encryption key derivation
• bcrypt password hashing
• CSRF protection and rate limiting
• Persistent SSH host-key verification
• Session ownership checks
• Security headers and optional SSRF protection
• Optional, restricted Tailscale SSH integration

Deployment

• Docker and Docker Compose support
• Multi-architecture images for AMD64 and ARM64
• Reverse-proxy examples for nginx, Traefik, and Caddy
• Subfolder deployment support
• Persistent configuration and user data under /app/data

Quick start

docker run -d \
  --name webssh \
  -p 5000:5000 \
  -e CORS_ORIGINS=http://localhost:5000 \
  -v webssh_data:/app/data \
  --restart unless-stopped \
  ghcr.io/bifrost0x/webssh:1.0.0

Then open http://localhost:5000 and create the first administrator account.

Updating an existing Docker Compose installation

Back up your persistent data before updating, then run:

docker compose pull
docker compose up -d

Important notes

• WebSSH currently uses in-memory SSH session state and must run with a single application worker.
• Persistent tmux sessions require tmux to be installed on the remote SSH host.
• Tailscale SSH is disabled by default and uses the WebSSH node's shared Tailscale identity. Review the documented access restrictions before enabling it.
• Keep /app/data on a persistent Docker volume. It contains accounts, settings, encrypted keys, profiles, and the generated secret key.

Thank you to everyone who tested WebSSH, submitted feedback, or contributed improvements.

Questions, ideas, and feature requests are welcome in GitHub Discussions.