Connecting¶

Muxus dials the way ssh does. This page describes what happens between selecting a host and reaching a prompt.

Resolution¶

Every connection starts by resolving the host through the OpenSSH configuration: a sequential, first-obtained-wins lookup across every matching Host pattern, wildcards and negations included, and every Included file, accumulating IdentityFile, CertificateFile and the *Forward directives. Each hop resolves independently, so a jump host uses its own key and its own user.

Match blocks are not applied. Their conditions depend on runtime state Muxus does not reproduce, so the options inside them are skipped.

Which keywords are honoured

Host keys¶

Before authentication, the server's key is checked against ~/.ssh/known_hosts and the read-only /etc/ssh/ssh_known_hosts, hashed entries included.

• Unknown host: the fingerprint is shown for confirmation. Accepting appends the key to ~/.ssh/known_hosts, so ssh on the command line trusts it as well.
• Changed key: a warning is shown. Accepting performs the ssh-keygen -R-style replacement of the old entry.

Authentication order¶

Within one connection Muxus follows the OpenSSH order and stops at the first method that succeeds:

1. Agent: every identity in the host's IdentityAgent, falling back to SSH_AUTH_SOCK when no override is configured.
2. Certificates: a CertificateFile together with its matching IdentityFile.
3. Keys: the IdentityFiles in the block, or the default ~/.ssh/id_* set. Passphrase-protected keys issue a prompt. IdentitiesOnly yes is honoured.
4. Keyboard-interactive: 2FA codes, challenge/response.
5. Password, with retries.

Agent approval time does not consume ConnectTimeout. If an agent accepts a request but never answers, Muxus shows what it is waiting for and moves to the next authentication method after a bounded wait. The host editor's Specific key file mode writes IdentitiesOnly yes and therefore skips the login agent entirely.

An SSH password prompt offers Remember this password. A single hidden keyboard-interactive field explicitly labelled as a password offers it too, for network devices that use keyboard-interactive for password login. The password is saved only after authentication succeeds. The first save creates a vault and asks for a master password of at least eight characters. By default, the vault key is kept in the OS credential store, so routine SSH use does not prompt for the master password. In Settings → Passwords, the policy can instead ask once when Muxus starts or whenever a saved credential is needed. The master password is always required to view or edit saved values.

If a never-prompt vault is restored without its OS credential-store entry, the next saved password use asks for the master password and attempts to restore automatic access. The credential can still be used for that connection if the OS store remains unavailable; the prompt policy can also be changed or the vault reset. Private-key passphrases, 2FA codes and all other keyboard-interactive answers remain transient and are never remembered. See the security model.

Jump chains and ProxyCommand¶

ProxyJump chains, including nested and comma-separated ones, are dialled hop by hop, each with its own resolution, host-key check and authentication. Cycles are detected and rejected.

ProxyCommand is supported as a transport. Muxus runs the command and speaks SSH over its stdin/stdout, which supports tools such as cloudflared access ssh and corporate ProxyCommand wrappers.

Forwards declared on the block (LocalForward, RemoteForward, DynamicForward) start with the session, and ForwardAgent applies when an agent is present.

One connection per host¶

Connections are multiplexed, the way OpenSSH ControlMaster sharing works. When a session's resolved dial plan matches a live connection, it opens a new channel instead of a new TCP connection. The comparison covers every hop's user, host, port and agent-forwarding policy, plus any expanded ProxyCommand. Splitting a pane, opening a second tab on the same host, the file browser, the remote editor, tunnels and ad-hoc forwards all share one SSH transport:

• no second login and no second 2FA prompt;
• servers that cap connections per user (MaxStartups, firewall rules) see one connection, no matter how many panes are open;
• sessions started together, such as a restored workspace, collapse into a single dial with a single authentication round-trip.

Sharing is safe by construction: a connection whose keepalives have gone quiet is not reused, and if the server refuses another channel on a shared connection (MaxSessions), Muxus silently dials a dedicated connection for that pane instead.

Each consumer holds its own lease on the transport:

• closing one tab does not affect the others; the connection closes with its last consumer;
• a tunnel holds its own lease, so closing every terminal leaves it running.

Connection loss¶

Muxus sends an SSH keepalive after 30 idle seconds by default. Settings → Behavior changes that fallback interval, while an explicit ServerAliveInterval in the matching OpenSSH configuration takes precedence:

With Automatically reconnect remote sessions enabled, a dropped connection is retried a few times before waiting for a key press. You can also use Reconnect from the tab menu. SSH tabs additionally offer Reconnect + tmux and Reconnect + screen, which dial a fresh transport and then reattach the existing multiplexer session.

Force reconnect (new connection) in the tab menu replaces one tab's connection, even while the session is live. It never multiplexes onto an established transport, so it also recovers an ended SSH tab whose shared connection went dead while other tabs still hold it. Once the replacement is up, new sessions to that host use it instead of the old transport.

The workspace dialog reconnects selected ended sessions, all ended sessions, or force-reconnects every remote tab. Force reconnect ends live shells; use tmux or screen when remote programs must survive. Saved tunnels keep their existing connections: the replaced transport carries them until they stop, while new sessions and new tunnels use the replacement.