Skip to main content

Connections

A connection points a block at a shell somewhere other than your local machine: a remote host over SSH, or a local WSL distribution (Windows only). Once a terminal block is connected, file preview, the system monitor widget, and the in-terminal Agent can all follow it to the remote side too, provided the remote helper (wsh) is running there.

This page covers SSH and WSL connections. AWS S3 connections are a third, unrelated connection type — they only work in file preview blocks (S3 has no shell to run a terminal in) and are not covered here.

Opening a connection​

Choose the pane connection here; the connection applies to that pane.
Choose the pane connection here; the connection applies to that pane.View full size ↗

Every terminal block header shows a connection indicator (a computer icon and the connection's name, or Local for your own machine). Click it to open the connection switcher.

The switcher is a type-ahead list with a few groups:

  • Local — your own machine, plus any WSL distributions Termia found (Windows only).
  • Remote — SSH hosts, sourced from your saved Vaults host entries (not parsed live from ~/.ssh/config; see below).
  • A Disconnect entry, shown only while the block's current connection is connected.
  • A reconnect entry, shown only when the block's current connection is disconnected or in an error state and you haven't typed anything.

Use the arrow keys and Enter to pick an item, or type to filter. Escape closes the switcher without changing anything.

Adding a brand-new SSH connection from the switcher​

If what you type doesn't match anything in the list, the switcher offers to create it as a new connection — but only if it looks like `user@203.0.113.10` (a literal IPv4 or IPv6 address). Typing a bare hostname or an alias from ~/.ssh/config that isn't already known to the switcher is rejected with "Invalid format. Use user@ip (IPv4 or IPv6)."

To connect to a host by name (an ~/.ssh/config alias, or a hostname you haven't saved anywhere yet), use one of these instead, all of which accept any hostname:

  • Save the host in Vaults — it then appears in the switcher's Remote list.
  • Run `wsh ssh user@host` in an existing terminal (add -n to open a new block instead of switching the current one).
  • Add it directly to connections.json — see Per-connection configuration below — or with `wsh conn add user@host`.

Once a host has connected successfully (by any of these paths), it also shows up in the switcher from then on, because Termia writes it back into connections.json and, separately, into Vaults (see Password reuse below).

WSL distributions​

On Windows, Termia reads the list of installed WSL distributions from the Windows Registry every time you open the switcher — there's nothing to configure. Pick one from the Local group, or run `wsh wsl -d <distribution-name>` from a terminal; with no -d, it uses your WSL default distribution. WSL support does not exist on macOS or Linux (there is no distro registry to read).

How ~/.ssh/config is read​

Once you connect to a host — whether from the switcher, Vaults, wsh ssh, or wsh conn connect — Termia resolves its connection settings from three layers, in this order (later layers win):

  1. Your ~/.ssh/config (and /etc/ssh/ssh_config, or %PROGRAMDATA%\ssh\ssh_config on Windows).
  2. That connection's entry in connections.json, if `conn:ignoresshconfig` is not set (the default). If it is set, step 1 is skipped entirely and only built-in OpenSSH defaults plus connections.json apply.
  3. Identity files are handled separately and are additive rather than overriding — see Authentication below.

The parser ignores Match directives; conditional settings in those sections are not applied. A file containing Match does not fail as a whole. ProxyJump is supported, but ProxyCommand and a user-facing local/remote/SOCKS tunnel manager are not implemented. Test configurations that depend on those features before relying on this client. Only the following supported keywords affect connection setup:

KeywordWhat Termia does with it
HostOnly patterns without *, ?, or ! are listed as connections; wildcard patterns are still consulted when resolving values for a specific host.
UserDefaults to your local OS username if unset.
HostNameDefaults to the Host pattern itself if unset.
PortDefaults to 22.
IdentityFileMay repeat; each is tried in order (see Authentication).
BatchModeyes disables all interactive prompts (password, passphrase, keyboard-interactive). Anything else is treated as no.
PubkeyAuthenticationAnything other than no is treated as enabled — including unbound and host-bound, which Termia does not otherwise distinguish.
PasswordAuthenticationAnything other than no is treated as enabled.
KbdInteractiveAuthenticationAnything other than no is treated as enabled.
PreferredAuthenticationsComma-separated order to try publickey, keyboard-interactive, password. gssapi-with-mic and hostbased are not implemented and are skipped if listed.
AddKeysToAgentOnly literal yes adds a decrypted key to your local SSH agent; confirm or a time value behaves like no.
IdentityAgentPath to the agent socket. If unset, Termia reads $SSH_AUTH_SOCK from your local shell.
IdentitiesOnlyyes/no; restricts auth to the identity files listed (plus the ones Vaults or connections.json add — see below).
ProxyJumpComma-separated list of jump hosts (or none to disable). See Jump hosts.
UserKnownHostsFile / GlobalKnownHostsFileSpace-separated lists of known_hosts files. Defaults to ~/.ssh/known_hosts ~/.ssh/known_hosts2 and /etc/ssh/ssh_known_hosts /etc/ssh/ssh_known_hosts2. If you're root, only the global files are consulted.

Any other keyword in your config file is ignored, even though the parser still reads past it.

Authentication​

Check the address, username and port in General before reviewing authentication settings.
Check the address, username and port in General before reviewing authentication settings.View full size ↗

Termia builds the list of auth methods to try from PreferredAuthentications (default publickey,keyboard-interactive,password), skipping any method that resolved to disabled above.

Keys​

Identity files come from four sources, tried in this order for each connection attempt, with duplicates removed (first occurrence wins):

  1. Your local SSH agent ($SSH_AUTH_SOCK, or the socket named by IdentityAgent) — every signer the agent already offers is tried first. Skipped entirely if IdentitiesOnly is yes.
  2. The key(s) chosen on a matching host entry in Vaults — either a key file path, or a key held in Termia's own encrypted key store (unlocked with a passphrase prompt the first time it's needed in a session).
  3. `ssh:identityfile` values you set directly in connections.json for that connection.
  4. IdentityFile lines from ~/.ssh/config (or the OpenSSH default key filenames if none are set and `conn:ignoresshconfig` is on).

Each candidate is tried one at a time — Termia deliberately does not hand the SSH library the whole batch at once, so a passphrase prompt appears only for the key actually being tried, and a key that fails to parse is silently skipped rather than aborting the whole list. If a key file needs a passphrase, you're prompted for it (unless BatchMode is on, which disables the prompt and skips that key). With `AddKeysToAgent yes`, a successfully decrypted key file is added to your local agent so you aren't asked again this session.

Passwords​

If you type a password to authenticate, and the connection succeeds, Termia saves it into a Vaults host entry for that IP + user automatically. The next time you connect, the password callback checks Vaults first and reuses it silently — you're only prompted again if no saved password matches. This lookup happens by exact IP and username match, not by SSH config alias.

If neither an agent, Vaults, nor a config-supplied key resolves, and password/keyboard-interactive auth is enabled, you're prompted through a dialog. Keyboard-interactive questions from the server are shown one at a time, honoring the server's request to mask or echo each answer.

Host key prompts​

Termia checks the host key against your known_hosts files (UserKnownHostsFile / GlobalKnownHostsFile, resolved as described above) using the same verification logic as OpenSSH:

  • Unknown host (no matching entry anywhere): you're shown the key's fingerprint and asked to confirm. Confirming appends it to the first known_hosts file Termia can write to, creating the file (and its parent directory) if none exist.
  • Changed host key (an entry exists but doesn't match): the connection is refused outright, with an error describing which files and keys are involved. Termia does not offer an in-app way to accept a changed key — you resolve it the same way you would with OpenSSH, by removing the stale line from the listed known_hosts file(s) yourself (or by removing and re-adding the host in Vaults, which purges the app's own cached session for that host+port).
  • Revoked key: refused outright, no prompt.

Agent forwarding​

Termia does not implement OpenSSH-style agent forwarding (ForwardAgent) — there is no option to forward your local agent socket into a remote session so that host can authenticate onward to a third host using your local keys. What it does support is using your local agent to authenticate to the host you're connecting to (see Keys above), and jump hosts (next section), which is a different mechanism.

Jump hosts​

ProxyJump (a comma-separated list of hosts) chains connections via TCP forwarding: Termia connects to the first jump host directly, then dials the next hop through that already-open SSH client, and so on until it reaches the real target. Each hop in the chain is resolved purely from ~/.ssh/config/connections.json for that hop's own name — flags or keywords you passed for the final destination are not applied to intermediate jumps. Chains longer than 10 hops are rejected.

Per-connection configuration (connections.json)​

Beyond ~/.ssh/config, Termia keeps its own per-connection settings file, connections.json, in the app's config directory. Find the exact path with:

wsh wavepath config

(the file is connections.json inside that directory). It's a JSON object keyed by the connection's display name — the same string you'd type to connect, e.g. `myuser@myhost` or `wsl://Ubuntu` — each holding any of these keys:

KeyTypeMeaning
conn:wshenabledboolWhether the remote helper (wsh) is used for this connection. Written automatically the first time you answer the install prompt; defaults to the global conn:wshenabled setting (true) until then.
conn:askbeforewshinstallboolWhether to prompt before installing wsh on this connection. Once a connection object exists (after any successful connect) and this key is absent, Termia treats it as already answered and stops asking — this is why re-installs after an update happen silently.
conn:wshpathstringOverride path to the wsh binary on the remote. Defaults to `~/.termia/bin/wsh`.
conn:shellpathstringOverride shell to launch on the remote. Defaults to the remote's $SHELL.
conn:ignoresshconfigboolSkip ~/.ssh/config entirely for this connection; only OpenSSH built-in defaults plus this file apply. Default false.
display:hiddenboolHide this connection from the switcher. Default false.
display:ordernumberSort position in the switcher (ascending). Default 0.
term:fontsize, term:fontfamily, term:themenumber / string / stringPer-connection terminal overrides; block-level metadata still wins over these.
cmd:envobjectExtra environment variables injected into shell sessions on this connection (requires wsh).
cmd:initscript, cmd:initscript.sh, cmd:initscript.bash, cmd:initscript.zsh, cmd:initscript.pwsh, cmd:initscript.fishstringA script, or a path to one, run once wsh initializes the session. The most shell-specific one that applies wins (requires wsh).
ssh:user, ssh:hostname, ssh:portstringOverride the matching ~/.ssh/config value, or set it outright if conn:ignoresshconfig is on.
ssh:identityfilestring[]Additional identity files, tried before ~/.ssh/config's. `wsh ssh -i <file>` on a successful connect appends here automatically.
ssh:identitiesonly, ssh:batchmode, ssh:pubkeyauthentication, ssh:passwordauthentication, ssh:kbdinteractiveauthentication, ssh:addkeystoagentboolSame meaning as the matching ~/.ssh/config keyword.
ssh:preferredauthenticationsstring[]Same meaning as PreferredAuthentications.
ssh:identityagentstringSame meaning as IdentityAgent.
ssh:proxyjumpstring[]Same meaning as ProxyJump.
ssh:userknownhostsfile, ssh:globalknownhostsfilestring[]Same meaning as the matching ~/.ssh/config keyword.

Example — hide a connection you only keep around for Git operations, and give another one its own theme:

{
    "git@github.com": {
        "display:hidden": true
    },
    "myuser@myhost": {
        "term:theme": "warmyellow",
        "term:fontsize": 16
    }
}

Or manage individual fields from a terminal instead of hand-editing the file — see the wsh conn reference for add / set / rm.

What gets installed on the remote (~/.termia)​

When wsh is enabled for a connection (it is by default; see below for when it's asked), a successful connect does the following on the remote host, all under its home directory:

  1. Detects the remote OS/architecture (uname -sm) and copies the matching wsh binary to `~/.termia/bin/wsh` over the SSH/WSL session (no separate file-transfer channel is used).
  2. Starts `wsh connserver` on the remote over that same session, and opens a Unix domain socket (SSH: an SSH-forwarded Unix socket; WSL: `~/.termia/wave-remote.sock`) that carries the RPC connection back to your local Termia.
  3. Writes shell integration files for whichever shells it finds under `~/.termia/shell/{zsh,bash,fish,pwsh}`, plus supporting state under `~/.termia/shell-cwd` and `~/.termia/env-updates`. These are what let a remote shell report its current directory back to the preview/file widgets and restore it on reconnect.
  4. Adds `~/.termia/bin` to PATH for that session, and injects a handful of environment variables (TERM_PROGRAM=termia, TERMIA=1, TERMIA_BLOCKID, TERMIA_CLIENTID, TERMIA_CONN, TERMIA_TABID, TERMIA_VERSION, TERMIA_WORKSPACEID), plus any `cmd:env` entries and `cmd:initscript*` from connections.json.

Only bash, zsh, fish, and pwsh are supported for shell integration. If the remote's default shell is something else, integration is skipped for that session; you can point `conn:shellpath` at one of the supported shells instead.

If any of this fails, Termia falls back to a plain SSH/WSL session without wsh — the terminal still works, but file preview, the system monitor widget, and the remote Agent are unavailable for that connection until it's fixed.

The first-time install prompt​

The very first time Termia connects to a host with conn:wshenabled true and no conn:askbeforewshinstall recorded yet for it (both true by default), you're asked to confirm before anything is installed, with an option to stop asking for every future connection. Your answer is written back to connections.json as conn:wshenabled, so:

  • Decline, and that connection never gets wsh (or the prompt) again unless you flip conn:wshenabled back to true yourself.
  • Accept, and wsh installs; the connection object now exists, so every later reconnect (and every version update — see below) proceeds silently, with no further prompts.

Keeping the remote helper up to date​

Every connect (and reconnect) runs `wsh version` on the remote first. Termia compares that version against its own build version with semver:

  • Remote version older than the local app → wsh and its shell integration files are re-pushed automatically, with no prompt (per the rule above). A short "Transferring wsh…" / "Installing shell scripts…" progress bar appears in the block while this happens.
  • Remote version equal or newer → left alone. Termia never downgrades a remote wsh.
  • Remote reports "not-installed" → treated the same as "older": full install runs.

You can force a fresh reinstall regardless of version — useful if a remote binary got corrupted or you changed conn:wshpath — with:

wsh conn reinstall <connection>

or from a terminal block, the same eye-off/"Wsh is not installed" icon that appears next to the connection indicator whenever wsh failed to come up on a connected session; clicking it re-enables conn:wshenabled, connects if needed, reinstalls, then reconnects.

Connection status and errors​

The connection indicator's color and the block's status overlay reflect the connection's current state:

  • Connecting — an animated indicator while the SSH/WSL handshake and (if enabled) wsh install are in progress.
  • Connected — normal state; the indicator uses one of a rotating set of colors, one per distinct active connection, so you can tell blocks on different hosts apart at a glance.
  • Disconnected — shown after a clean close, with a Reconnect action in the block.
  • Error — the SSH/WSL connection itself failed (auth, network, host key, etc.). The error text is shown in the block, with a copy button, and a Reconnect action to retry.

Separately, a connection can be connected but without wsh — the terminal works, but the banner explains why the remote helper isn't available, with one of several distilled hints depending on the underlying error: the remote disk is full, the install directory isn't writable, the remote filesystem is read-only, or the remote OS/architecture isn't supported. A button on that banner lets you permanently disable wsh for the connection (writes `conn:wshenabled: false` to connections.json) if you'd rather stop seeing the warning than fix the underlying problem; another dismisses the current error without changing the setting.

Debugging a connection​

The block's gear menu has a Debug Connection submenu (Off / Info / Verbose). Turning it on logs the SSH/WSL handshake, key attempts, and wsh install steps directly into that terminal block while it (re)connects — this is the fastest way to see which identity file or auth method is actually being tried. The full daemon log is also always available:

wsh wavepath log --tail   # last 100 lines
wsh wavepath log -o       # open it in a new block

Disconnect and reconnect​

Closing a connection (the switcher's Disconnect item, `wsh conn disconnect`, or the remote end dropping the session) tears down the SSH client or WSL command, the domain socket, and the remote connserver process. Only the switcher's Disconnect item also resets the block back to your local shell (ConnDisconnectCommand on its own never touches which connection a block points at).

An unexpected drop — network blip, remote reboot, the OS suspending your laptop — is treated as "disconnected," not "error," so the block simply shows the reconnect action rather than a scary error state. Reconnecting re-runs the entire flow from scratch: SSH/WSL handshake, auth, host key check, and the version-gated wsh update check above — nothing about a prior session is assumed to still be valid.

If several terminal blocks in the same tab were opened together as a synchronized group, changing one block's connection through the switcher carries the new connection over to the rest of that group automatically; disconnecting or reconnecting a single block does not.