vmuxAgent

What vmuxAgent is

vmuxAgent is a tiny Mac app that lives in your menu bar and pretends to be a regular SSH agent. It exposes a Unix domain socket at ~/.ssh/vmux-agent.sock and speaks the standard SSH agent wire protocol that ssh, git, rsync, scp, and every other Mac SSH client already know how to talk to. Point SSH_AUTH_SOCK at it and your Mac uses vmuxAgent instead of ssh-agent.

The difference is where the keys live. A normal ssh-agent holds private keys in your Mac's memory, decrypted from ~/.ssh/id_*. vmuxAgent holds nothing. When an SSH client asks for a signature, vmuxAgent forwards the request over an encrypted Multipeer Connectivity (MPC) link to RemoteSignerPhone on your iPhone. The phone signs with a key that lives in its Secure Enclave, prompts you with Face ID or Touch ID, and returns the signature. The private key never reaches your Mac.

Why use it

If you keep SSH keys on your laptop, anyone with access to that laptop has access to those keys. Strong passphrases help, but only as long as the agent isn't already unlocked. With vmuxAgent + RemoteSignerPhone, your authoritative SSH key never leaves your iPhone's hardware. Every signing operation requires biometric approval. Lose the laptop and an attacker still cannot SSH anywhere as you.

It is also faster than the alternatives: there is no YubiKey to plug in, no PIN to remember, no smart-card reader to install. The phone is already in your pocket and Face ID is already calibrated.

Key features

• Drop-in SSH agent. Speaks the same wire protocol as ssh-agent. Works with ssh, git, scp, sftp, rsync, mosh, and any other tool that reads SSH_AUTH_SOCK.
• Per-key biometric approval. Each signature on the iPhone requires Face ID or Touch ID. Approvals are not cached at the Mac.
• Session certificate. On every successful pairing, vmuxAgent asks the phone's CA for a short-lived SSH certificate (8 hours by default) so frequent signatures don't blow up your biometric attention. Long-running keys still require per-signature approval.
• Encrypted MPC pairing. All Mac/iPhone traffic uses MultipeerConnectivity with encryptionPreference: .required. Pairing happens over BLE plus Wi-Fi or AWDL. No router, account, or relay server is involved.
• APNs wake. When the phone goes to sleep and an SSH client signs, vmuxAgent fires an Apple Push Notification at RemoteSignerPhone, which wakes up, reconnects, and approves the signature. You see one notification on the iPhone, tap to approve, and ssh finishes.
• Public-key cache. vmuxAgent persists the list of public keys advertised by the phone, so ssh-add -l and git push keep working even when the iPhone is briefly off the network. Signing still requires the phone.
• Sandboxed and tiny. No daemons, no launchd plists, no privileged helpers. The agent runs as your user and writes one file (~/.ssh/vmux-agent.sock).

How it fits together

ssh / git / scp                  Mac                                  iPhone
     |                                                                  |
     | reads SSH_AUTH_SOCK                                               |
     v                                                                  |
~/.ssh/vmux-agent.sock --> vmuxAgent ---- MultipeerConnectivity -----> RemoteSignerPhone
                            (menu bar)    (Wi-Fi / AWDL, encrypted)     (Secure Enclave + Face ID)
                                ^
                                |
                               APNs wake push (when phone is asleep)

The Mac never sees a private key. The iPhone never sees the network beyond the local link to your Mac. The bridge between them is the only thing your terminal session depends on.

System requirements

The phone does not have to be unlocked when you start an SSH command. APNs wake will get its attention. It does, however, need to be powered on and in range of either Wi-Fi or Bluetooth.

Where to go next

• Getting started walks through your first connection end to end.
• Menu bar reference lists every item in the dropdown.
• SSH CLI integration covers SSH_AUTH_SOCK, shell setup, agent forwarding, and tool compatibility.
• Keys and certificates explains the cache, the session certificate, and the lifecycle of each key.
• iPhone pairing covers MPC discovery, repairing, and switching phones.
• Security is the threat model, what is and is not protected.
• Troubleshooting for when something is wrong.

The phone-side companion is documented at RemoteSignerPhone. The combined family of apps is at all vmux apps.