Pairing and Discovery

How discovery works

RemoteSignerPhone advertises itself on the local network using Apple's Multipeer Connectivity framework — the same transport AirDrop uses. The service type is vmuxsigner and the iPhone broadcasts its name (the value of Settings → General → About → Name) as the peer identifier.

Multipeer Connectivity uses a hybrid of Wi-Fi and Bluetooth to find peers. As long as the iPhone and the requesting device are on the same Wi-Fi SSID, or close enough for Apple's BLE peer discovery, they will find each other within a second or two. There is no internet hop, no router-side forwarding, and no centralized service in between.

The Multipeer session is configured with encryptionPreference: .required. Anything sent between the iPhone and the paired device is encrypted point-to-point.

Connection states you will see

The Transport section on the home screen shows the current state of the iPhone's signer host. Possible values:

When a paired peer disconnects (Mac sleeps, app quits, network changes), the state drops back to Advertising.

What the user sees on each side

Open both apps at once for the cleanest first pairing. With RemoteSignerPhone in the foreground showing Status: Advertising, do one of the following depending on which side initiates:

Pairing from a Mac

• Open vmuxAgent on the Mac. From its menu bar item, choose Pair iPhone (or your version's equivalent — see the vmuxAgent setup guide).
• The Mac sends a Multipeer invitation to the iPhone's advertised peer.
• The iPhone accepts the invitation automatically — there is no Allow / Deny prompt at the pairing step. Pairing acceptance is implicit because the invitation is local-network only and signing approval is biometric per request anyway.
• The Transport status updates to Connecting to <Mac name> and then Connected to <Mac name>.
• The Status banner shows Shared <N> signer(s) with <Mac name>. once the Mac requests the key list.

Pairing from Apple Vision Pro

• Open vmux on the headset and start a connection to a host whose authentication is Remote Signer.
• The headset broadcasts a Multipeer invitation as it begins the SSH handshake.
• The iPhone accepts and the Transport status updates as above.
• See SSH signing with iPhone for the visionOS-side connect details.

Why there is no Allow / Deny at pairing time

Two reasons. First, the Multipeer Connectivity layer is already secured: it requires AirDrop-style local proximity and encrypted sessions, which raises the bar above remote network attacks. Second, and more importantly, every individual signature still requires Face ID or Touch ID. A malicious peer could pair with your iPhone and still produce zero signatures, because each request raises a biometric prompt that you'd see and deny. The pairing handshake by itself doesn't authorize anything — it just opens a channel for sign requests, which are independently approved.

Switching Macs

Multipeer Connectivity in this app is configured for one connected peer at a time. If you take the iPhone to a different Mac (a second laptop, a desktop, a friend's Mac with vmuxAgent installed):

1. Quit vmuxAgent on the previous Mac, or sleep that Mac. The session drops; Transport shows Advertising.
2. Launch vmuxAgent on the new Mac and pair from there.
3. Transport flips to Connecting to <new Mac> and then Connected.

If both Macs are awake and running vmuxAgent simultaneously, the iPhone will be paired with whichever one invited it most recently. There is no UI to manually pick — the iPhone accepts invitations as they come.

Pairing with multiple devices

The iPhone is one peer. It can hold one Multipeer session at a time with the agent. However, it can fluidly switch between the Mac (via vmuxAgent) and the Vision Pro (via vmux directly) because each is a discrete session. In practice you'll see the Transport status flip between Mac and headset as you initiate connections from one or the other.

If you have, say, the Mac and the headset both trying to talk to the iPhone within the same second, one will win the invitation and the other will retry. This rarely matters in practice because user-driven connect actions don't overlap that closely.

Unpairing

There is no explicit "unpair" button on the iPhone — pairing is ephemeral, not persisted. To break a pairing:

• From the iPhone: force-quit RemoteSignerPhone (swipe up from the App Switcher and flick it away). Any active Multipeer session ends. When you relaunch the app, advertising resumes from a clean state.
• From the Mac: quit vmuxAgent. The agent stops talking to the iPhone. The iPhone's Transport returns to Advertising.
• From the headset: close the vmux window or disconnect the host. The Multipeer session ends.

Because there is nothing persisted about a Mac on the iPhone (no "remember this device" record), revisiting the same Mac later just re-pairs from scratch. The same is true on the Mac side — vmuxAgent does not remember individual iPhone identities across launches; it discovers fresh each time. This is a deliberate simplification: the only state that matters is the public keys themselves, which are advertised over the channel each time.

Network requirements

If pairing fails consistently, check Settings → RemoteSigner → Local Network is enabled. If it is, toggle Wi-Fi off and back on — Multipeer can get into a bad state when networks change rapidly, especially when the iPhone leaves a corporate Wi-Fi for cellular.

Switching iPhones

If you upgrade to a new iPhone, your Secure Enclave keys do not migrate. Even with an iCloud restore, Apple invalidates Secure Enclave-backed Keychain items on a new device by design — the private key material is hardware-bound to the original iPhone's chip.

To migrate to a new iPhone:

1. Install RemoteSignerPhone on the new device.
2. Provision a fresh identity (or several).
3. Add the new public keys to your servers' authorized_keys.
4. Optionally, remove the old public keys from authorized_keys and securely retire or wipe the old iPhone.

This is by design. The whole point of the Secure Enclave is that the key cannot be cloned. The cost is that you re-enroll on hardware change.

Related

• vmuxAgent setup — Mac-side pairing and SSH_AUTH_SOCK configuration.
• SSH signing with iPhone — visionOS-side connect flow.
• Background wake — how APNs keeps the iPhone reachable when locked.