Skip to content
ZestSSH Docs

Windows Native Integration

ZestSSH on Windows integrates with the operating system through URL scheme registration, background connection management, and a native Inno Setup installer.

URL Scheme Registration

Section titled “URL Scheme Registration”

ZestSSH registers the zestssh:// custom URL scheme on Windows so that external applications, scripts, and web pages can trigger actions within ZestSSH.

Section titled “Supported Deep Links”
URLAction
zestssh://connection/newOpen the new connection screen
zestssh://connection/edit/<id>Edit a specific connection
zestssh://import/ssh-configOpen SSH config import
zestssh://snippetsOpen the snippets screen
zestssh://settingsOpen settings
zestssh://connect?host=X&user=Y&port=ZQuick connect to a server
zestssh://execute?connection=X&command=YExecute a command on a connection
zestssh://snippet?connection=X&name=YRun a saved snippet
zestssh://batch?connections=A,B,C&command=Y&timeout=Z&parallel=trueBatch execute across multiple connections
zestssh://workflow?name=X&key=YRun a saved workflow
zestssh://auth/callback?token=XOAuth callback for desktop authentication

Registration

Section titled “Registration”

The URL scheme is registered via the Windows Registry under HKCU\Software\Classes\zestssh. This registration is performed at install time by the Inno Setup installer. It is a per-user registration that does not require administrator privileges.

Security

Section titled “Security”

Deep link connections require explicit approval through a security callback (onConnectionRequested). If the callback is not set, deep-link connection requests are silently blocked. This prevents malicious web pages from triggering unauthorized SSH connections via crafted zestssh:// URLs.

Additionally, all incoming deep link URIs are length-bounded to 2,048 bytes to prevent malicious payloads from causing memory issues.

Background Connections

Section titled “Background Connections”

On Windows, ZestSSH manages background SSH connections differently from Android:

  • No foreground service: Windows does not require a persistent notification to keep background processes alive (unlike Android).
  • The Dart isolate handles all SSH traffic regardless of window state.
  • Minimizing ZestSSH to the system tray keeps connections alive.
  • The tray icon provides quick access to reconnect or open the main window.

System Tray

Section titled “System Tray”

When minimized, ZestSSH sits in the Windows system tray with:

  • A tray icon indicating active connections.
  • Right-click context menu with:
    • Show Window — Restore the main window.
    • Quick Connect — Open the quick connect dialog.
    • Quit — Close all windows and end all sessions.

Inno Setup Installer

Section titled “Inno Setup Installer”

ZestSSH for Windows is distributed as a traditional Inno Setup executable installer (.exe), not a ZIP archive.

Why Inno Setup

Section titled “Why Inno Setup”
  • Registry integration: Properly registers the zestssh:// URL scheme, file associations (.zest, .zestheme), and uninstall entries.
  • Start Menu and Desktop shortcuts: Created during installation.
  • Clean uninstall: Removes all installed files, registry entries, and shortcuts.
  • User experience: Familiar wizard-based installation that Windows users expect.

Installation

Section titled “Installation”
  1. Download the ZestSSH-Setup-x.x.x.exe installer.
  2. Run the installer (no administrator privileges required for per-user install).
  3. Follow the installation wizard.
  4. ZestSSH is available from the Start Menu and optionally the Desktop.

Uninstallation

Section titled “Uninstallation”
  1. Go to Windows Settings > Apps > Installed apps.
  2. Find ZestSSH and click Uninstall.
  3. The Inno Setup uninstaller removes all program files, registry entries, and shortcuts.

Note: User data (connections, identities, settings) stored in %APPDATA% and secure storage is not removed by the uninstaller. To fully remove all data, delete the ZestSSH folder in %APPDATA% after uninstallation.

Build Configuration

Section titled “Build Configuration”

Release builds for Windows require environment variables passed via --dart-define-from-file=.env. This includes API keys for RevenueCat, Firebase, and the sync server. See the project’s build documentation for details.

Secure Storage on Windows

Section titled “Secure Storage on Windows”

On Windows, FlutterSecureStorage uses the Windows Credential Manager (DPAPI-backed) to store sensitive data:

  • Identity passwords and private keys
  • PIN hashes and lockout state
  • Auto-backup passwords
  • Sync credentials

Data is encrypted with the user’s Windows login credentials via DPAPI (Data Protection API), providing protection at rest.

Desktop Shell Features

Section titled “Desktop Shell Features”

On Windows, ZestSSH uses the desktop shell layout with:

  • Sidebar navigation — Connection list, identities, favorites, and settings.
  • Tab bar — Multiple terminal sessions in tabs.
  • Split panes — Up to 8 layout presets (side-by-side, stacked, grid, etc.).
  • Command palette (Ctrl+Shift+P) — Quick access to all actions.
  • Window management — Resize, minimize to tray, fullscreen (F11).

See Keyboard Customization for the full list of 40+ desktop shortcuts.