Pairing with iPhone
How vmuxWatch links to vmuxPhone, what flows between them, and what to do when the link drops.
The relay model
vmuxWatch and vmuxPhone talk over Apple's WatchConnectivity framework. There is no cloud component, no external server, and no separate account. The iPhone is the source of truth; the watch is a viewer that the iPhone keeps up to date.
This means three practical things:
- The watch only sees what the iPhone is willing to send. No private keys, no host passwords (only a one-way reference), no scrollback beyond the visible screen.
- Pairing happens in the standard iOS Watch app, not inside vmux. There is no separate vmux pairing step.
- When the link drops (range, sleep, charger), updates pause. They resume the moment the link is back, and the watch catches up automatically.
Pairing checklist
There is no in-app pairing flow inside vmuxWatch. Pairing is the standard Apple Watch pairing relationship plus app installation:
- Pair your Apple Watch with your iPhone using the iOS Watch app, if you have not already.
- Install vmuxPhone on the iPhone and add at least one host.
- Install vmuxWatch on the watch — it appears in Watch app → My Watch → Available Apps as soon as vmuxPhone is installed. Tap Install.
- Launch vmuxWatch. The Status section flips to Phone reachable within seconds.
If you have multiple iPhones, the watch follows whichever one it is currently paired to. Re-pairing the watch to a different iPhone redirects vmuxWatch to that iPhone's workspace; you cannot pull data from both.
What flows from the iPhone to the watch
| Data | Sent to watch | Notes |
|---|---|---|
| Saved host labels (title, hostname, port, username) | Yes | Read-only on the watch. |
| Host passwords | No (one-way) | The iPhone keeps passwords in its Keychain. The watch can ask the iPhone to open a saved host by reference, but it never receives the password itself unless the watch user typed one in directly. |
| Secure Enclave keys | No | Cannot leave the iPhone hardware. |
| Open window list | Yes | With state, status line, and which window is selected. |
| Terminal snapshot | Yes | Visible screen only, as a character grid (not pixels). |
| Scrollback | No | Only the visible screen is sent. |
| Connection state | Yes | Connected / Connecting / Failed / Disconnected. |
| Notifications | Yes | iOS routes vmuxPhone notifications to the watch automatically when the watch is on your wrist. |
What flows from the watch to the iPhone
| Action | Sent to iPhone | Notes |
|---|---|---|
| Tap a window | Focus request | iPhone selects that window and pushes the latest snapshot. |
| Tap a host | Open request | iPhone opens or focuses a window for that host. |
| Manual host configuration | Full config | Used only for the Connect Manually flow on the watch. |
| Viewport size | Columns and rows | Recomputed when display mode changes; iPhone respects this for cold-start sessions opened from the watch. |
| Keystrokes | Text + mode (prose or command) | iPhone forwards them as PTY input. |
| Special keys | Esc, Tab, Enter, Backspace, arrows | Encoded as the right escape sequences on the iPhone. |
| Tmux shortcuts | Symbolic | iPhone replays them as the right tmux key sequence. |
| Toggle connection | Reconnect / disconnect | iPhone reconnects or disconnects the session. |
How updates are throttled
vmuxPhone debounces snapshot updates by about 120 ms so a chatty terminal does not saturate the WatchConnectivity link. When the watch is reachable, the iPhone uses live sendMessage calls. When the watch is not reachable, the iPhone falls back to updateApplicationContext (single most-recent state) and transferUserInfo (queued history). Either way, the watch sees the latest state when it next activates.
This means short bursts of output appear nearly live; sustained streams of output are coalesced. You will not see every line of dmesg -w, but you will see what is happening.
What happens when the iPhone is far away
| iPhone state | Watch behaviour |
|---|---|
| In Bluetooth range, app foreground | Live updates. |
| In Bluetooth range, app background | Live updates while iOS keeps WatchConnectivity warm. May lag by a second or two. |
| iPhone screen locked | Updates continue; iOS routes them through the relay even with the screen off. |
| iPhone in Low Power Mode | Updates may batch more aggressively. Catches up on next wake. |
| Out of range, both on Wi-Fi | Updates continue over Wi-Fi if both devices share the same network. |
| Out of range, no shared Wi-Fi | Status flips to Phone not reachable. Watch shows last cached state. |
| iPhone powered off | Same as out of range. |
| iPhone unpaired from this watch | Watch sees no data at all. Re-pair in the iOS Watch app. |
What happens when the iPhone is asleep
The iPhone does not need to be unlocked or in the foreground for the relay to work. iOS wakes the WatchConnectivity service as needed. The one exception: when you tap a host on the watch that is not yet open, the iPhone may present a Notification Center banner instead of unhiding the app. Tap the banner on the iPhone to complete Face ID and finish bringing the session up.
Foregrounding the iPhone from the watch
Tapping a session on the watch sends a focus request to the iPhone. The iPhone:
- Selects that window in its workspace.
- Brings vmuxPhone to the foreground if iOS allows it (subject to Apple's user-attention rules — the screen has to wake).
- Connects the session if it is currently disconnected.
If the iPhone is locked and you do not pick it up, the foregrounding is queued behind a notification banner.
Geometry hints from the watch
When you open a session from the watch, the watch sends the iPhone the column and row count that fits the watch screen at the current display mode (Dense or Readable). The iPhone honors this on the cold-start render so the snapshot fits the watch without ugly truncation. After the iPhone takes over visually (because you foregrounded the app), the geometry follows the iPhone's terminal view.
You will not see anything different in the iPhone UI when this happens.
Privacy and battery
- The relay does not need any iOS permission beyond the standard pairing relationship — no microphone, camera, or location.
- Watch dictation uses the watch microphone; that capture stays on the watch and is converted to text before any keystroke leaves the device.
- The relay is on whenever both apps are installed and at least one host exists. To suppress relay traffic completely, close every window in vmuxPhone — with no windows there is nothing to send.
Common pairing problems
- Watch shows "Phone not reachable" and never flips: Open vmuxPhone on the iPhone; iOS sometimes only wakes WatchConnectivity once the phone-side app has run.
- Watch shows a stale window list: Pull the watch out of your sleeve; raising your wrist activates the session and triggers a refresh.
- Watch shows hosts but no sessions: That is correct if the iPhone has nothing open. Tap a host to ask the iPhone to open one.
For the full troubleshooting matrix, see Troubleshooting.
Related
- vmuxPhone — Watch pairing — the iPhone-side reference for the same link.
- Viewing sessions — what to do once the link is live.
- Input on watch — typing through the relay.