Connecting to remote hosts

Two ways to connect

vmuxMac gives you two equally valid ways to start a remote session. Pick the one that fits your habits and use the other when it is more convenient.

1. The local shell — every new window starts a real shell on your Mac, so you can simply type ssh user@host or mosh user@host exactly the way you would in Terminal.app. Your existing ~/.ssh/config, agent, and known_hosts apply.
2. vmux managed connections — vmuxMac's saved-host store, connection form, and built-in vsh shell can manage SSH and Mosh sessions for you, share profiles with the rest of the vmux family, and use device-bound keys held in the macOS Keychain.

This page is the Mac-specific guide. The cross-cutting guides cover protocol details: SSH, Mosh, and Authentication methods.

Connecting from the local shell

Because vmuxMac launches a normal login shell, all of your existing tooling works without any extra setup:

ssh user@example.com
ssh -p 2222 user@example.com
ssh -i ~/.ssh/work_ed25519 user@example.com
mosh user@example.com

Your ~/.ssh/config is honored, including Host aliases, ProxyJump, ProxyCommand, and IdentityFile. The system SSH agent (ssh-agent) and the macOS keychain-backed agent both work, including ssh-add --apple-use-keychain.

If you have vmuxAgent running, set SSH_AUTH_SOCK to its socket and any local-shell ssh command will use your iPhone Secure Enclave keys for signing:

export SSH_AUTH_SOCK=$HOME/.ssh/vmux-agent.sock
ssh user@example.com

Connecting through vmux managed sessions

vmuxMac shares the saved-host model with vmux on visionOS and vmuxPhone. That means a host you save once is available everywhere you sign in.

Open a managed connection one of three ways:

• Run connect in vsh to bring up the connection form.
• Run ssh user@host in vsh (note: vsh's ssh command is different from the system ssh — vsh creates a vmux managed session, the system ssh runs as a regular subprocess).
• Open the command palette with Cmd+Shift+P and run Connect.

The connection form asks for the same fields as the rest of the vmux family:

Select Connect to start the session. If a host with the same address and username is already saved, vmuxMac reuses that profile. If not, the host is added to your saved-hosts list.

Saved-host management — naming, grouping, exporting, and importing — is identical to the visionOS app. See Saved hosts and Import / export for details. You can also drive everything from vsh.

SSH authentication

vmuxMac supports the four SSH authentication methods used by the vmux family:

1. Password — typed into the connection form and stored encrypted in the macOS Keychain. Auto-filled on reconnect.
2. Secure Enclave device key — a P-256 key generated and held in the Mac's Secure Enclave. The private key never leaves the chip.
3. System SSH agent — vmuxMac honors SSH_AUTH_SOCK and forwards signing requests to whatever agent is running. This is the right choice when you use vmuxAgent for iPhone-backed signing.
4. Companion-app remote signer — your iPhone (running RemoteSignerPhone) signs each authentication challenge with Face ID or Touch ID approval.

Pick a method per host in the connection form, or set a default and override per host. See the cross-cutting Authentication methods guide for setup instructions.

Importing existing keys

If you already have an OpenSSH key on disk (for example ~/.ssh/id_ed25519), you can import it into vmuxMac so it is available to managed sessions:

1. Open the command palette and run Import SSH Key, or use vsh: key-import ~/.ssh/id_ed25519.
2. If the key is encrypted, enter its passphrase. The decrypted key is re-encrypted with your Mac's Keychain.
3. Optionally tag the key with a name and use it as the default key for one or more hosts.

Imported keys remain in ~/.ssh untouched. vmuxMac stores its own encrypted copy.

Mosh

Mosh works just like SSH but tolerates network changes and intermittent connectivity. To connect:

mosh user@example.com

…in the local shell, or run mosh user@host inside vsh. vmuxMac uses the same authentication you set up for SSH (Mosh negotiates the initial session over SSH).

If mosh-server is not installed on the remote host, install it there first (apt install mosh, brew install mosh, etc.). The mosh-status command in vsh prints diagnostic information about your local Mosh setup and recommends a working configuration if anything is missing.

For protocol detail, see Mosh.

Known hosts and host key checking

Local-shell ssh uses your usual ~/.ssh/known_hosts file and prompts you for unknown hosts the way Terminal.app would.

Managed vmux sessions maintain a separate known-hosts store inside the app. The first time you connect to a host, vmuxMac shows the server's host fingerprint and asks you to confirm. Once accepted, that fingerprint is pinned. If a future connection presents a different fingerprint, vmuxMac refuses the connection and shows a clear warning so you can investigate.

Reconnecting

If a managed session disconnects — server restart, network drop, or a deliberate disconnect — the window shows a disconnected overlay with a Reconnect button. Selecting it reuses the saved profile.

For unstable networks, Mosh is the better choice; it roams across networks and recovers from suspends without losing state. SSH connections drop on the same events.

Environment

Managed vmux sessions set the same environment variables as vmux on visionOS:

Local-shell sessions instead identify as xterm-ghostty because the terminal engine is libghostty. You can override either with a custom env line in your shell startup if a remote tool misbehaves.

Where to go next

• SSH — full SSH reference.
• Mosh — full Mosh reference.
• Authentication methods — passwords, Secure Enclave, agent, remote signer.
• Saved hosts — naming, grouping, defaults.
• vmuxAgent — iPhone-backed signing for any local-shell SSH command.