Module ssh 

SSH terminals (P2 of SPEC_REMOTE_TERMINALS_AND_DURABLE_SESSIONS_2026_10_02.md).

A pane on an SSH connection runs the system ssh in its PTY (spec §3.1): the user’s own ~/.ssh/config, keys, agent and known hosts apply, and ssh asks for a password, a passphrase or a new host key in the terminal itself, where the user answers it. The askpass bridge (§5.3), which an agent’s non-interactive use needs, comes later.

Enums

Control

What to ask a shared connection (ssh -O).

Constants

EXIT_CONNECTION_FAILED

ssh exits 255 when it could not connect, could not authenticate, or the connection dropped; any other code is the remote command’s own.

NAME_HASH_HEX 🔒

Hex characters of the connection name’s hash in a socket’s name.

SOCKET_NAME_MAX 🔒

The longest socket name ssh binds in a control dir: the name’s hash, -, the 40-hex %C, and while binding . plus 16 random characters.

Functions

binary

The ssh to run: the first on PATH, then (Windows) the OpenSSH client Windows installs, which an inherited PATH can lack.

binary_for_user

binary for the user’s own interactive ssh pane, whose prompts are the user’s to answer in it: a native client is preferred whatever its version (Windows 10’s inbox OpenSSH is 8.1), still for its name resolution.

connection_lost

Whether ssh ending with code means it had no connection, or lost it, rather than that the remote shell ended (exit included). A session on a shared connection that was closed or died ends this way too.

control

The ssh arguments asking dest’s shared connection in dir to op: the same socket a pane’s launch shares.

control_dir

Where ControlMaster sockets go (macOS and Linux; Windows’ OpenSSH has no connection sharing): a private, owner-only directory, since anyone who can open a socket there can use the connection. None (no sharing; ssh still connects) if it can’t be made so, or a socket in it would be too long.

control_dir_in 🔒

control_dir under base: base/ssh-<8 hex of config_home>, each level owner-only. A test can pass its own base.

control_path_option 🔒

ControlPath= for dest’s shared connection in dir: <name hash>-%C. ssh’s %C hashes the user, host and port ssh resolves, not the name it was given, so two aliases for one account (one with a key, one password-only) shared whichever connection logged in first, and the password-only one got in without asking (#4513). The connection’s own name keeps them apart; %C stays so an alias pointed elsewhere gets a new connection.

forces_askpass 🔒

Whether ssh is OpenSSH 8.4 or newer, which honours SSH_ASKPASS_REQUIRE=force; asked once per binary (ssh -V).

is_posix_layer_build 🔒

An ssh.exe built for MSYS2 or Cygwin: its runtime DLL sits beside it. Never true off Windows.

launch

The ssh arguments for a pane. control_dir, on macOS and Linux, is where connection-sharing sockets live (ControlMaster), so a second pane on the same connection reuses the first one’s and asks for nothing.

launch_exec

The ssh arguments for one command run without a terminal (an agent’s Shell): launch’s, with -T in place of -tt, since its output is read, not a session shown.

lost_message

What the connection’s status says when a pane’s ssh lost it.

lost_note

The line a plain SSH pane shows, under ssh’s own reason, when it has no connection: the pane stays, and Enter starts ssh again.

missing_binary_message

What to say when there is no ssh, with how to get it on this platform.

on_path 🔒

openssh_version 🔒

(major, minor) from ssh -V’s “OpenSSH_9.5p2, …” or “OpenSSH_for_Windows_8.1p1, …”.

pane_lost_connection

Whether a pane’s ssh, ended with code, lost its connection (or never had one). stopped_by_srv: srv ended it itself (the pane closed, or restarted), and ssh then exits 255 too (closing its pty does, and a session on a shared connection does on SIGTERM), which is no lost connection.

pick 🔒

binary’s order: the first preferred ssh on PATH, then Windows’ own client if preferred, else the first on PATH, else Windows’ client.

private_dir 🔒

Make dir (mode 0700), or accept it if it already exists as a real directory owned by this user that no one else can enter. /tmp is shared: someone else could have made the directory, or a symlink in its place.

push_destination 🔒

The port, if any, then -- and the destination: -- ends ssh’s options, so the destination can never be read as one (conn.rs also refuses a leading -).

quote

One word for a POSIX shell: single-quoted, with ' written as '\''.

quote_path

quote for a remote path, leaving a leading ~ or ~/ unquoted so the remote shell expands it to the remote home (OSC 7 and users write it).

remote_command

The command line ssh hands to the remote user’s login shell: the pane’s command, run in cwd when one is set, or for a plain pane with a cwd, the login shell started there. None for a plain pane with no cwd: ssh then starts the login shell itself.

set_pane_env

Name the pane in launch’s SetEnv too (AGENTMUX_BLOCKID), so a host that accepts it (AcceptEnv AGENTMUX_*) lets the pane’s stats badge find its shell there (PaneProcs). Dropped quietly by any other host, like the rest of that SetEnv. A block id is AgentMux’s own UUID; anything with another character is left out rather than quoted.

shared_control_dir

control_dir for this srv’s channel: where every ssh it runs to a host (panes, agents’ commands, the helper, files) shares one connection. None where ssh can’t share connections, and then there is nothing to ask -O.

socket_fits 🔒

Whether ssh can bind a socket in dir: the longest path it binds is dir/<name hash>-<40-hex %C>.<16 random> (SOCKET_NAME_MAX), and it has to fit in sun_path with its NUL.

windows_client 🔒

Windows’ own OpenSSH client, if installed; None elsewhere.