Watch Pairing
Pair vmuxPhone with vmuxWatch and what data flows between them.
What pairing gives you
A paired Apple Watch running vmuxWatch becomes a wrist-side, read-only viewer of the same workspace you have open on the iPhone. The watch shows:
- The list of saved hosts (without passwords).
- The list of currently open windows with their host labels.
- Per-window snapshots of the last screenful of terminal output.
- Connection state, working directory, and unread-activity badges.
- Tap notifications when something noteworthy happens.
You can tap a host on the watch to ask the iPhone to open it. You cannot type into the terminal from the watch — the watch is a viewer, not an input device.
Requirements
| Requirement | Minimum |
|---|---|
| iPhone | Running vmuxPhone with at least one host saved. |
| Apple Watch | Apple Watch with watchOS 10 or later. |
| Pairing | The watch must be paired to this iPhone in the Watch app on iOS. |
| Install | vmuxWatch must be installed on the watch — install via Watch app → My Watch → Available Apps. |
A vmuxWatch app icon installs automatically when both apps are present and the watch app catalog refreshes. The first install can take a few minutes; opening the Watch app on the iPhone speeds it up.
How the relay works
vmuxPhone relays workspace changes to the watch through Apple's WatchConnectivity framework. There is no cloud component. The relay carries three classes of message:
| Message | Sent on | What it carries |
|---|---|---|
| Bootstrap | First activation; reconnection | The full host list, the open window list, the selected window, and the current snapshots. |
| Window list changed | A window opens, closes, or selection changes | The updated window list and selection. |
| Snapshot update | Terminal output arrives or connection state changes | A WatchTerminalSnapshot for the affected window. |
vmuxPhone debounces snapshot updates by ~120 ms to keep the connectivity bandwidth modest. The snapshot is a downsampled, character-grid representation tuned for the watch screen size — not a full pixel image.
When the watch is reachable, messages are sent live with sendMessage. When it is not, vmuxPhone falls back to updateApplicationContext (a single most-recent state) and transferUserInfo (a queued history) so the watch sees the latest state next time it activates.
Pairing flow
There is no explicit pairing step inside vmuxPhone. Pairing is the standard iOS Watch pairing flow:
- Open the Watch app on iPhone.
- Pair your Apple Watch with this iPhone (or confirm it is already paired).
- Make sure vmuxWatch is installed.
- Open vmuxPhone and add at least one host. As soon as the workspace exists, vmuxPhone activates the relay and the watch sees data.
If you have multiple iPhones, the watch follows the iPhone it is paired with. There is no way to mirror to a watch paired with a different iPhone.
What flows to the watch
| Data | Flows to watch | Notes |
|---|---|---|
| Saved host labels and destinations | Yes | Read-only on the watch. |
| Per-host passwords | No | Passwords are Keychain-only and never leave the iPhone. |
| Secure Enclave keys | No | Cannot leave the iPhone hardware. |
| Open window list | Yes | Including selection and unread badge. |
| Terminal snapshots | Yes | Last screenful, character-grid form. |
| Scrollback | No | Only the visible screenful is sent. |
| Live keystrokes | No | The watch is read-only. |
| Connection state | Yes | Connected / Connecting / Disconnected / Failed. |
| Notifications | Yes | Bell, command-completed, and disconnect events surface as Watch notifications when iOS routes them there. |
Foregrounding from the watch
Tap a session on the watch. The watch sends a focus request to the iPhone via the relay. vmuxPhone responds by:
- Selecting the matching window (or creating one if it has been closed since the watch last refreshed).
- Bringing itself to the foreground (subject to iOS' user-attention rules — the screen has to wake).
- Connecting if disconnected.
If the iPhone is locked, iOS shows a Notification Center banner instead of unhiding the app. Tap the banner to complete Face ID and unhide the terminal.
Geometry hints
When you open a session from the watch, the watch supplies the expected columns and rows for its small screen. vmuxPhone honors that geometry on the first connect so the watch's snapshot can be rendered without scrollback truncation. After the iPhone takes over (because you foregrounded the app), the geometry follows the iPhone's terminal view.
This is purely an optimization for cold-start sessions opened from the watch. You will not see anything different in the iPhone UI.
Permissions
The relay does not require any iOS permission beyond the standard pairing relationship. There is no microphone, camera, or location involvement. The relay is on whenever both apps are installed and at least one host exists; turning the watch off (or unpairing) silently disables the relay until both come back.
Battery considerations
The relay activity is small. Sending one snapshot per ~120 ms is well below the WatchConnectivity throttle for normal use. If you have many windows producing constant output, vmuxPhone coalesces snapshots so that the watch does not get a burst per packet.
If you want to suppress relay traffic completely, close every window in vmuxPhone — with no windows, the relay sends only the host list and stops.
Limitations
- vmuxPhone supports one Apple Watch per iPhone. Multiple watches paired in rotation is not tested — the most recently activated watch is the one that sees fresh data.
- The watch app cannot type into the terminal in this release. A future release may add a preset-snippet send action.
- Unsynced changes can lag while the watch is on the charger (fewer wake events). They catch up when the watch is on your wrist again.
Troubleshooting
Watch shows No iPhone
The relay is not active. Open vmuxPhone on the iPhone and add at least one host. If the workspace is empty, there is nothing for the watch to show. Once the workspace exists, the watch updates within seconds.
Watch shows stale data
WatchConnectivity sometimes batches updates aggressively. Open the watch app to wake it; the relay catches up on next activation.
Tapping a session on the watch does nothing
The iPhone is asleep. iOS requires user attention before unhiding an app — tap the watch tap-back banner on the iPhone, or pick up the iPhone to wake it.
Watch session shows blank terminal
The relay snapshot has not arrived yet. Wait a moment; the next snapshot tick will fill the screen. If it persists for more than a few seconds, force-quit and re-open both apps.
Related
- vmuxWatch manual — the watch-side reference.
- Workspace — the iPhone-side workspace the watch mirrors.
- Notifications — how alerts get to the watch.