Getting Started

What you'll do

This walkthrough takes about ten minutes. By the end, your Mac will use your iPhone's Secure Enclave for every SSH key operation. You will install two apps, pair them once, point your shell at vmuxAgent's socket, and run ssh user@host to confirm.

Prerequisites

• A Mac running macOS 14 Sonoma or later.
• An iPhone running iOS 17 or later with Face ID or Touch ID enrolled.
• Both devices on the same Wi-Fi network, or both with Bluetooth on.
• A remote host you can already log into. (Password access is fine for now — we will add the new public key in step 5.)

You do not need to be signed into the same Apple ID, but it is recommended; same iCloud account makes Multipeer discovery noticeably faster.

Step 1. Install vmuxAgent on the Mac

Install vmuxAgent from the Mac App Store, or download it from the vmux website. On first launch you will see a menu bar icon shaped like a key. The icon is hollow when no iPhone is paired and filled when a pair is connected.

The first launch silently creates ~/.ssh/vmux-agent.sock with mode 0600 (owner read/write only). If ~/.ssh/ does not exist, vmuxAgent creates it.

Step 2. Install RemoteSignerPhone on the iPhone

Install RemoteSignerPhone from the App Store. On first launch the phone generates a Secure Enclave SSH key and asks for permission to use the local network and Bluetooth — both are required for Multipeer Connectivity. Approve both prompts. Allow notifications too; the wake push depends on it.

Once the phone shows "Ready to sign" on its home screen, your default identity is provisioned. The private key never leaves the Secure Enclave; only the public key is shared with the Mac.

Step 3. Pair the two apps

Open vmuxAgent's menu and confirm the iPhone has been discovered. Discovery is automatic — neither side has a "pair" button. The Mac advertises and browses for the vmuxsigner Multipeer service, and the iPhone advertises the same. As soon as both apps are open and on the same link, they invite each other and connect.

You will see two changes:

• The Mac menu bar icon switches from hollow to filled.
• The Mac menu shows Connected to iPhone Name and a list of advertised public keys.

If discovery does not happen within thirty seconds, see iPhone pairing for troubleshooting.

Step 4. Point your shell at vmuxAgent

Open the vmuxAgent menu and click Copy SSH_AUTH_SOCK Command. This puts the right export line on your clipboard, with the absolute path to your home directory baked in. Add it to your shell startup file so every new terminal sees it. For zsh:

echo 'export SSH_AUTH_SOCK="$HOME/.ssh/vmux-agent.sock"' >> ~/.zshrc

For bash:

echo 'export SSH_AUTH_SOCK="$HOME/.ssh/vmux-agent.sock"' >> ~/.bash_profile

Open a new terminal so the new environment is loaded. Confirm the variable is set:

echo $SSH_AUTH_SOCK
# /Users/you/.ssh/vmux-agent.sock

Step 5. List the keys vmuxAgent advertises

Run ssh-add -l. This calls into vmuxAgent over the socket and asks for the list of identities, which vmuxAgent in turn pulls from the iPhone:

ssh-add -l
# 256 SHA256:abc... iphone-secure-enclave (ECDSA)

You should see one line per key on the phone. The fingerprint here is the same fingerprint shown in the menu bar dropdown.

If you also want a copy of the OpenSSH-formatted public key (for pasting into a server's ~/.ssh/authorized_keys), run:

ssh-add -L > ~/Desktop/iphone-pubkey.pub

Append the resulting line to authorized_keys on every host you want to log into using the iPhone-held key.

Step 6. Connect

Run ssh against a host that now trusts the iPhone's public key:

ssh user@example.com

The first time you do this, your iPhone will buzz and show a Face ID prompt: Approve SSH login to example.com. Authenticate. The signature returns to the Mac, the SSH handshake completes, and you are at the remote shell prompt.

If your iPhone is locked or the screen is off, an APNs push notification will arrive on the lock screen. Tap it, RemoteSignerPhone opens, the Mac reconnects over MPC, and the same Face ID prompt appears. The whole round-trip takes 3–6 seconds.

Step 7. Confirm everything is wired through the agent

Run a tool that uses the agent transparently — git is the most common:

git clone git@github.com:you/private-repo.git

If GitHub already trusts the iPhone-held public key (paste it under Settings -> SSH and GPG keys on github.com), you will see one Face ID prompt and the clone will start.

Optional: add agent forwarding

If you SSH into a bastion and want the next hop to use the same iPhone-held key, add ForwardAgent yes to the relevant ~/.ssh/config block, or pass -A on the command line. See SSH CLI integration for caveats.

Where to go next

• Menu bar reference — what every item in the dropdown does.
• Keys and certificates — how the public-key cache and session certificate work.
• Security — what the model protects against.
• RemoteSignerPhone — phone-side identity, multi-key management, and lock behavior.