Pairing with Vision Pro
How MacKeyHost advertises itself, how vmux discovers it, and how to manage trusted Macs and repair discovery.
How pairing works
MacKeyHost and vmux find each other using Apple's MultipeerConnectivity framework. There is no relay server, no Apple ID lookup, and no manual numeric code to enter. Both apps speak a single Bonjour service type:
_vmuxmackey._tcpWhen MacKeyHost launches it starts an MCNearbyServiceAdvertiser for that service, advertising the Mac's hostname as the peer name. When you tap the Mac target in vmux's spatial keyboard on Vision Pro, vmux starts an MCNearbyServiceBrowser for the same service. The first time both sides are reachable to each other, vmux sends an invitation, MacKeyHost accepts it automatically, and an encrypted session opens (encryptionPreference: .required). After that, key and mouse events flow as small JSON envelopes inside the session.
There is no separate "pairing list" stored on disk. Every connection is established fresh on demand.
What "reachable to each other" actually means
Multipeer Connectivity uses three transports, in order of preference:
| Transport | Requirement | Range |
|---|---|---|
| Apple Wireless Direct Link (AWDL) | Wi-Fi on for both devices | Same room |
| Wi-Fi infrastructure | Both on the same Wi-Fi network | Same network segment |
| Bluetooth Low Energy | Bluetooth on for both | A few meters |
You don't choose; macOS and visionOS pick the best available. AWDL is fastest and the most common when both devices are awake on Wi-Fi. Bluetooth-only is the slow fallback — it works, but key latency on BLE is noticeably higher (50–100 ms per event versus 5–15 ms on Wi-Fi).
For pairing to succeed, at least one transport has to be live on both ends. If you turn Wi-Fi off on the Mac and Bluetooth off on the Vision Pro, the two will never see each other.
What you see on the Mac
The MacKeyHost window has one status badge that cycles through these states:
| Badge | Color | Meaning |
|---|---|---|
| Offline | red | Advertiser not running. App was just launched and startAdvertising() hasn't completed, or you stopped advertising. |
| Advertising | orange | The Mac is broadcasting _vmuxmackey._tcp and waiting for a Vision Pro to invite it. This is the normal idle state. |
| Connecting to peer | orange | Invitation received from a Vision Pro; session is being established. Lasts a fraction of a second. |
| Connected to peer | green | Encrypted session open. Events are being received. The events counter ticks up; the last event is shown beneath. |
Below the badge, when at least one event has been received, the window shows the running event count and a one-line description of the most recent event — useful for confirming the link is alive (e.g. ⌘ 'a' for Cmd+A, escape for the escape key, Mouse: move for pointer motion).
What you see on the Vision Pro
Open vmux's spatial keyboard. The target selector at the bottom of the keyboard shows vmux (default — types into the active SSH/local session) and Mac. Tap Mac.
A status line above the keyboard cycles through:
| Status | Meaning |
|---|---|
| Disconnected | No browser running yet. Toggling Mac starts it. |
| Searching... | Browsing for _vmuxmackey._tcp advertisers on the local link. |
| Connecting to Mac... | A Mac was found; an invitation has been sent. |
| Connected to Mac | Session is open. Keys typed here go to the Mac. |
If multiple Macs are advertising on the same network, vmux invites the first one it sees. To pick a different Mac, see "Multiple Macs" below.
First-time pairing checklist
If pairing doesn't happen within 30 seconds, walk this list:
| Check | Fix |
|---|---|
| MacKeyHost window says Advertising | If it says Offline, quit and relaunch the app. |
| Local Network permission on the Mac | macOS Settings → Privacy & Security → Local Network → vmux Mac Keyboard on. iOS-style prompt only appears once; if you missed it, toggle it manually. |
| Local Network permission on the Vision Pro | visionOS Settings → vmux → Local Network on. |
| Same Wi-Fi network or BLE in range | Toggle Wi-Fi off and on, ensure Bluetooth is on, retry. |
| VPN active on the Mac | Some VPNs block multicast. Disconnect VPN; pair; reconnect VPN once paired (the link survives). |
| Personal hotspot active | Sharing connectivity from one device to the other often blocks MPC discovery. Use shared infrastructure Wi-Fi instead. |
| Mac is asleep or screen locked | Wake it. Sleeping Macs do not advertise. |
If the basics check out and pairing still fails, see Troubleshooting for how to capture logs.
Trust model
MacKeyHost auto-accepts every invitation it receives. There is no "trust this Vision Pro" prompt, no QR code, no PIN. The reason: discovery is already gated on being physically nearby (BLE) or on the same network segment (Wi-Fi/AWDL). Anyone who can reach the advertised service is, by Apple's design, on the local link with you.
The link itself is end-to-end encrypted by encryptionPreference: .required, so traffic can't be eavesdropped or tampered with by other devices on the same Wi-Fi network. But anyone in your physical environment with vmux on a Vision Pro could pair if MacKeyHost is running with no other Vision Pro currently connected.
If that matters in your environment — a shared office, a public space — quit MacKeyHost when you're not using it. The dock icon and Cmd+Q are sufficient. There is no daemon left running. See Security and permissions for the full threat model.
Repairing after a drop
A "lost" pair is almost always one of:
- The Vision Pro went to sleep. Take it off, the eye sensors detect that you're not wearing it, and the visionOS app suspends. MacKeyHost falls back to Advertising. Put the headset back on, return to vmux, tap Mac in the keyboard target — pairing reopens within a few seconds.
- The Mac went to sleep. macOS suspends the advertiser. Wake the Mac and watch the badge return to Advertising. The Vision Pro will reconnect on the next keystroke if it's still browsing.
- Wi-Fi changed. Joining or leaving a VPN, switching SSIDs, or moving rooms can drop the AWDL link mid-session. The next event from the Vision Pro will trigger automatic reconnection if both ends still have a transport.
You do not need to do anything special to "re-pair." Just bring both apps back into a connected state.
Multiple Macs
If you have more than one Mac running MacKeyHost on the same network, vmux on Vision Pro will invite the first one it discovers. There is currently no in-app picker for choosing among advertised Macs.
Workarounds:
| Goal | How |
|---|---|
| Pair to a specific Mac when others are nearby | Quit MacKeyHost on the Macs you don't want to use. The remaining one becomes the only advertiser. |
| Switch between Macs frequently | Toggle the Mac target off in vmux, quit MacKeyHost on the current Mac, launch on the new one, re-toggle. |
| Tell two Macs apart in the picker | macOS uses the system hostname as the peer display name. Set descriptive names in System Settings → General → Sharing → Local Hostname (e.g. studio-mac, office-mac). |
Pairing one Vision Pro to one Mac at a time is supported. Two different Vision Pros can each pair with the same Mac, but not simultaneously — MacKeyHost holds one open session and rejects new invitations while it is busy. The first to invite wins; the second has to wait for the first to disconnect.
Stopping advertising
To take the Mac off the network without quitting the app, close the MacKeyHost window. Reopening it from the dock or Cmd+Tab calls startAdvertising() again and the badge returns to Advertising.
To stop entirely and free the socket, choose Quit from the dock menu or press Cmd+Q. There is no menu bar agent — once quit, the Mac is no longer discoverable.
Related
- Getting started — first-run pairing walkthrough.
- Input injection — what flows through the link once paired.
- Security and permissions — what the encrypted MPC link does and does not protect.
- Troubleshooting — when discovery or session setup fails.