DOCUMENTATION • DEPLOYMENT & RUNTIME GUIDES

Installation, Deployment & FAQs

Operating instructions for Windows x64, Linux distributions, source builds, and deep architectural answers to frequently encountered questions.

PLATFORMS

Prebuilt Standalone Releases

Windows (PowerShell 5.1+ / 7+)

Windows 10 / 11 64-bit

The Windows bundle is a fully self-contained release with an embedded Erlang 27 runtime. It does not require any prerequisite Elixir or Erlang installations, nor does it require OpenSSH-for-Windows.

# Recommended: download the installer from the latest published release:
# https://github.com/dineshkorukonda/ssh-client/releases/latest
# Run the downloaded .exe to open the native Windows application.

# Alternatively (PowerShell) — manual zip extract:
Invoke-WebRequest -Uri https://github.com/dineshkorukonda/ssh-client/releases/latest/download/ssh-client-windows-x64.zip -OutFile "$env:TEMP\ssh-client.zip"
Expand-Archive -Path "$env:TEMP\ssh-client.zip" -DestinationPath "$env:LOCALAPPDATA\Programs\ssh-client" -Force
& "$env:LOCALAPPDATA\Programs\ssh-client\ssh-client.exe"

Credential Storage: Windows Credential Manager under target prefix ssh-client:host:<hostname>.

Config Location: %APPDATA%\ssh-client\servers.json

Linux (x86_64, glibc 2.31+)

Ubuntu • Debian • Fedora • Arch

Linux releases are distributed as a standalone tarball containing OTP release executables and WebKitGTK runtime wrappers.

# Download release tarball (v0.0.76)
wget https://github.com/dineshkorukonda/ssh-client/releases/latest/download/ssh-client-linux-x64.tar.gz

# Unpack into target destination
sudo mkdir -p /opt/ssh-client && sudo tar -xzf ssh-client-linux-x64.tar.gz -C /opt/ssh-client

# Start the application (opens GUI in browser at http://localhost:4000)
/opt/ssh-client/bin/ssh_client start

Credential Storage: Freedesktop Secret Service via libsecret (secret-tool).

Config Location: ~/.config/ssh-client/servers.json

Building from Source

Elixir 1.18+ • Erlang/OTP 27+

If you wish to compile or develop directly against the repository:

git clone https://github.com/dineshkorukonda/ssh-client.git
cd ssh-client
mix deps.get

# Run interactive development session:
iex -S mix

# Or produce a production release bundle:
MIX_ENV=prod mix release ssh_client

QUESTIONS & ANSWERS

Frequently Asked Questions

Technical deep-dives into edge cases, security, and architecture.

Does ssh-client require OpenSSH to be installed on my machine?

No. Unlike most desktop terminal applications that spawn an external ssh.exe subprocess in the background, ssh-client uses Erlang/OTP's built-in :ssh application directly.

Protocol negotiation, key exchange, encryption ciphers, and PTY channels occur in native BEAM processes. It operates identically on clean Windows installations without OpenSSH-for-Windows installed on your system PATH.

How does the zero-wizard in-place auto-updater work?

The built-in updater (SSHClient.Updater) queries the GitHub Releases API for newer semver tags. When triggered:

It streams portable ZIP/tarball assets directly to a temporary staging workspace.
It validates directory structure, unzips runtime binaries, and stages the replacement release tree.
An atomic file replacement hot-swaps the application code and invokes :init.restart() for a seamless in-process restart.
No setup wizard dialogs, UAC re-prompts, or manual installer downloads are necessary.

How does the Dual-Pane SFTP Explorer and drag-and-drop file transfer work?

The SFTP explorer displays side-by-side local and remote filesystem panes with interactive breadcrumbs, permission badges, and instant folder navigation over OTP :ssh_sftp channels.

The HTML5 drag-and-drop bridge allows you to drag files directly from your desktop file manager or between the parallel panes to initiate binary file transfers with real-time transfer progress indicators and conflict prompts.

How does ssh-client handle private key passphrases without persisting them?

When a password-protected identity key (e.g. id_ed25519) is encountered, the client prompts for your passphrase once per active session.

The passphrase and decrypted key bytes are stored strictly in-memory via SSHClient.PassphraseCache. Decrypted material is never written to disk, never cached in local configuration files, and automatically purged when the process terminates.

What happens if a remote host's public key fingerprint changes?

ssh-client enforces strict host key verification. If a host key does not match the cached record in known_hosts, the connection is aborted immediately (reject-by-default).

A visual fingerprint diff (displaying algorithm, old SHA-256 fingerprint, and new fingerprint) is surfaced to the operator. The connection cannot proceed unless the user explicitly approves the host key change.

How is background CPU and network consumption kept low during monitoring?

Many monitoring tools keep full interactive SSH shells open or poll high-frequency commands repeatedly. ssh-client implements:

Non-interactive exec channels: Metrics are collected via ephemeral :ssh_connection.exec channels rather than held-open PTY sessions.
Focus-aware backoff: When a server panel or tab is unfocused, its poll interval dynamically backs off (e.g., from 5s to 30s+), reducing remote host load and battery consumption.

Where are imported SSH configurations and host metadata stored?

Configurations resolve via Erlang's standard :filename.basedir/3:

Windows: %APPDATA%\ssh-client\servers.json
Linux: ~/.config/ssh-client/servers.json

This file contains only connection metadata (host aliases, IP addresses, ports, auth methods). No private keys, passwords, or secret material are ever persisted in this file.