iPhone Pairing

How pairing works

vmuxAgent and RemoteSignerPhone use Apple's MultipeerConnectivity framework to find each other and exchange messages. There is no relay server, no Apple ID lookup, and no manual code entry. Both apps advertise the service vmuxsigner on the local link; the first time both are running and reachable to each other, the Mac sends an invitation, the iPhone accepts, and an encrypted session opens.

The session is encrypted with a key derived during MPC handshake (encryptionPreference: .required). Once established, both sides exchange RemoteSignerEnvelope messages — key list, sign requests, certificate requests, and device-token updates.

What "the local link" actually means

Multipeer Connectivity uses three transports, in order of preference:

You don't choose; macOS and iOS pick the best available. AWDL is the most common. For pairing to succeed, at least one of these has to be live on both ends — Bluetooth alone is enough at short range, Wi-Fi alone is enough on the same network.

The Mac and iPhone do not have to be on the same Apple ID, but it helps. macOS uses the system identity ring to pre-trust devices on the same iCloud account, which speeds up MPC discovery measurably (often to under a second versus 5-10 seconds).

First-time pairing

There is no pairing button. To pair for the first time:

1. Launch RemoteSignerPhone on the iPhone. Approve the prompts for local network and Bluetooth permission. Allow notifications.
2. Open the iPhone's app to the home screen and leave it foregrounded.
3. Launch vmuxAgent on the Mac.
4. Watch the menu bar key icon. Within 10–30 seconds it should fill in, and the dropdown should show Connected to iPhone Name.

The first connection seeds the certificate authority's public key on the Mac and pulls the phone's full identity list. After that, you can lock the iPhone and put it in your pocket — vmuxAgent will reconnect automatically the next time the phone wakes.

What to check if pairing doesn't happen

Run these in order. Each one rules out a common cause.

If pairing still doesn't happen after the checks above, see Troubleshooting for log capture and reset steps.

Re-pairing after a loss

The most common cause of a "lost" pair is the iPhone going to sleep. This is normal and recovery is automatic:

1. The iPhone screen is off; vmuxAgent reports Disconnected in its menu.
2. You run ssh user@host on the Mac.
3. vmuxAgent fires an APNs wake push. The iPhone receives it on the lock screen.
4. You tap the notification. RemoteSignerPhone opens. The Mac discovers the phone and reconnects.
5. The Face ID prompt for the signature appears. Approve.
6. The SSH handshake completes.

You do not need to repeat the first-time pairing steps. The Mac remembers the last device token and the cached public-key list across reboots and across iPhone sleep cycles.

If the iPhone has been off your network for an extended period and the device token has expired (rare; tokens last weeks), the wake push will silently fail. Open the RemoteSignerPhone app manually; it will receive a fresh token from APNs and send it to the Mac, which will store it for future wakes.

Switching to a different iPhone

If you replace your iPhone or want to use a different one as your signer:

1. Install RemoteSignerPhone on the new iPhone and complete its first-launch setup. The new phone will generate its own Secure Enclave keypair — this is a different key from the old phone.
2. Add the new public key to your servers' authorized_keys. (You can keep the old key authorized for grace, then remove it when ready.)
3. Quit RemoteSignerPhone on the old iPhone, or simply turn it off so MPC discovery only finds the new one.
4. On the Mac, click Refresh Keys in the vmuxAgent menu (or quit and relaunch vmuxAgent). The cache will repopulate from the new device.

vmuxAgent does not actively forget the old device; it tracks "the most recently connected peer." If both old and new iPhones are powered on and on the same network with the app open, MPC will pair to whichever responds first. Turn off the device you don't want to use.

To completely wipe state on the Mac side, quit vmuxAgent, delete ~/Library/Containers/app.vmux.agent/Data/Library/Preferences/app.vmux.agent.plist (or use defaults delete app.vmux.agent), and relaunch.

Multi-Mac and multi-phone caveats

vmuxAgent currently pairs one-to-one with the first RemoteSignerPhone it discovers. There is no UI to choose between multiple phones, though the cached device token is per-Mac (so two different Macs can each pair with the same iPhone independently).

Related

• Getting started for first-run pairing.
• Troubleshooting for failure modes and log capture.
• RemoteSignerPhone for phone-side identity setup.
• Security for what the encrypted MPC link does and does not protect.