Getting Started

What you need before you start

• A Mac running macOS 14 Sonoma or later, awake and unlocked.
• An Apple Vision Pro with vmux installed, awake and signed in.
• Both devices on the same Wi-Fi network, or close enough for Bluetooth to reach.
• Five minutes. There is no account to create.

You do not need to run any Terminal commands, install any helpers, or change any system files. MacKeyHost is a single sandboxed app and pairing is automatic.

Step 1 — Install MacKeyHost on the Mac

Open the App Store on the Mac, search for vmux Mac Keyboard, and install. The bundle is small (about 4 MB). On first launch you will see a window with a keyboard icon, the title vmux Mac Keyboard, and a status badge that reads Advertising in orange.

Leave the window open while you set things up. The status badge has to stay on Advertising or Connected for input to flow.

Step 2 — Grant Accessibility permission

The first time you launch MacKeyHost, the bottom of its window shows an orange warning panel:

Accessibility Permission Required System Settings → Privacy & Security → Accessibility [Open Settings]

Click Open Settings. macOS opens directly to the Accessibility pane. Find vmux Mac Keyboard in the list (you may need to scroll), and toggle the switch to on. macOS will ask for your password or Touch ID to confirm — this is normal for any change to the Accessibility list.

Switch back to MacKeyHost. The orange panel should disappear within a second or two. If it doesn't, quit MacKeyHost from the menu bar and relaunch — macOS sometimes needs a relaunch to pick up new Accessibility grants.

Without this step, the next steps will appear to work — vmux will pair, the event counter on the Mac will tick up — but no key will actually arrive in any Mac app.

Step 3 — Approve Local Network access

The first time MacKeyHost tries to advertise itself on the network, macOS shows a system prompt:

"vmux Mac Keyboard" would like to find and connect to devices on your local network.

Click Allow. If you click Don't Allow by accident, you can fix it later in System Settings → Privacy & Security → Local Network. Without local network permission, your Vision Pro will not see the Mac unless both ends fall back to Bluetooth (slower, shorter range).

Step 4 — Open vmux on Vision Pro and find the Mac

Put on the Vision Pro and open vmux. Trigger the spatial virtual keyboard from any open terminal window (use the standard keyboard ornament, or the keyboard button in the floating toolbar). At the bottom of the keyboard you'll see a target selector: vmux (the default, types into the SSH session) and Mac (types into MacKeyHost).

Tap Mac. vmux starts browsing for vmuxmackey advertisers on the local link. Within a few seconds, your Mac's hostname will appear in the picker. The status line above the keyboard will read Searching... while it looks, then Connecting to yourMac..., then Connected to yourMac.

On the Mac, watch the MacKeyHost window — the badge changes from Advertising to Connecting to Vision Pro, then settles on Connected to Vision Pro.

If the Mac never appears in the Vision Pro picker after 30 seconds, see Troubleshooting.

Step 5 — Send your first keystroke

On the Mac, click on a TextEdit window or Spotlight to give it focus. (MacKeyHost itself does not need to be frontmost — it injects into whatever Mac app is active.)

On the Vision Pro, with Mac selected in vmux's keyboard, type a few letters. The letters should appear in the Mac app the same instant your finger lifts off the spatial key.

In the MacKeyHost window, you'll see:

• Events: 5 (or however many keys you pressed)
• A small grey line showing the last received event, e.g. 'h' or ⇧ 'A'

If the event counter advances but no characters appear in the Mac app, the most likely cause is missing Accessibility permission. Re-check step 2.

Step 6 — Try modifiers and special keys

Still in vmux's spatial keyboard, with Mac selected, try:

• A capital letter using the on-screen Shift key. The Mac receives Shift + letter.
• The arrow keys. They navigate text exactly like a hardware arrow key.
• Cmd+Space. Spotlight opens on the Mac.
• Cmd+Tab. The Mac app switcher comes up.

Modifier behavior matches the standard Mac mental model — Cmd for Mac shortcuts, Ctrl for Unix terminal control, Option for special characters. See Input injection for the full mapping table and known limits.

Step 7 — Try the pointer

In vmux on the Vision Pro, open the touchpad ornament (the small trackpad surface that appears alongside the keyboard). Make sure Route to Mac is on. Drag a finger across the trackpad — the Mac's cursor should move under your virtual finger.

Tap with one finger to left-click. The Mac registers a click at the cursor's current location. Two-finger drag scrolls the frontmost Mac window. To drag-and-drop, tap-and-hold to start the drag, move, then lift to release.

The cursor stays on the Mac's main display and is clamped to its bounds — it can't slide off into another monitor or the menu bar.

What "done" looks like

You're done when:

1. MacKeyHost shows Connected to Vision Pro.
2. The Accessibility warning panel is gone.
3. Letters typed in the spatial keyboard with Mac selected appear in a Mac app within ~30 ms of release.
4. The pointer ornament moves the Mac cursor smoothly.

You only run through the install and permission steps once. Next time you launch MacKeyHost it remembers Accessibility, and pairing with the Vision Pro takes a few seconds.

Where to go next

• Pairing with Vision Pro — what happens on each side, multiple Macs, repairing.
• Input injection — modifier rules, mouse mechanics, what does and doesn't pass through.
• Security and permissions — encrypted transport, what an attacker on your Wi-Fi can and cannot do.
• Troubleshooting — when something is wrong.