Documentation

Installation, Deployment & FAQs

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

Operating System Setup

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.

# 1. Download release archive (v0.0.1)

Invoke-WebRequest -Uri https://github.com/dineshkorukonda/ssh-client/releases/download/v0.0.1/ssh-client-windows-x64.zip -OutFile "$env:TEMP\ssh-client.zip"

# 2. Extract to installation directory

Expand-Archive -Path "$env:TEMP\ssh-client.zip" -DestinationPath "$env:LOCALAPPDATA\Programs\ssh-client" -Force

# 3. Launch desktop client

& "$env:LOCALAPPDATA\Programs\ssh-client\bin\ssh_client.bat" start

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.

# 1. Download release tarball (v0.0.1)

curl -sSL -O https://github.com/dineshkorukonda/ssh-client/releases/download/v0.0.1/ssh-client-linux-x64.tar.gz

# 2. Unpack into target destination

sudo mkdir -p /opt/ssh-client && sudo tar -xzf ssh-client-linux-x64.tar.gz -C /opt/ssh-client

# 3. Start the application daemon or desktop window

/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

Frequently Asked Questions

Technical deep-dives into edge cases 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 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.

Can I run ssh-client in a web browser without the desktop window?

Yes. The desktop shell is powered by Phoenix LiveView inside an elixir-desktop container. If launched headless with mix phx.server or within a server environment, you can point any modern web browser to http://localhost:4000 to access the full UI and xterm.js terminal bridge.

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.