Getting Started
Install vmuxWatch on your Apple Watch and view your first paired session.
Before you start
vmuxWatch only works alongside vmuxPhone. You will not get past the Phone not reachable state without:
- An iPhone running vmuxPhone with at least one saved host.
- An Apple Watch paired to that iPhone in the standard iOS Watch app.
- Both devices on, unlocked at least once since the last reboot, and within Bluetooth range (or on the same Wi-Fi network).
If you have not set up vmuxPhone yet, follow vmuxPhone — Getting started first. Add at least one host. Come back here when you can see a green-dot session running on the iPhone.
Install vmuxWatch on your Apple Watch
vmuxWatch is bundled with vmuxPhone, so installing the iPhone app makes the watch app available automatically. There are two paths:
| Situation | What to do |
|---|---|
| You have Automatic App Install enabled in the Watch app | Wait. vmuxWatch appears on your watch within a minute or two of installing vmuxPhone. Charging the watch speeds it up. |
| You install apps manually | Open the Watch app on iPhone, scroll to Available Apps, find vmux, and tap Install. |
Once vmuxWatch is installed, raise your wrist and look for a small vmux icon on the home grid. Tap it.
Launch and authorize
The first time you open vmuxWatch:
- The Status section shows Phone not reachable for a moment, then flips to Phone reachable as the WatchConnectivity link establishes.
- The watch asks the iPhone for its current workspace. Within a second or two, the Phone Sessions and Hosts On Phone sections populate.
- If you previously saved manual hosts directly on the watch (rare), they show up under Saved.
There is no separate sign-in. The watch trusts the iPhone it is paired with.
If the Status section stays on Phone not reachable, see Troubleshooting.
See your paired sessions
The session list view has four sections you will care about:
| Section | What is in it |
|---|---|
| Status | Whether the iPhone is currently reachable from the watch. |
| Phone Sessions | Every window the iPhone has open right now, with its title, host label, and current status. |
| Hosts On Phone | The full list of saved hosts on your iPhone, regardless of whether they are connected. |
| Saved | Hosts saved directly on the watch (typically only used for the manual-connect path). |
The session that the iPhone has selected (the one currently in front on the iPhone) shows a small green broadcast icon next to its title.
View your first terminal
Tap any entry under Phone Sessions. The watch:
- Sends a focus request to the iPhone.
- Pushes a viewport hint (columns and rows that fit the watch screen at the current display mode) so the iPhone can render output appropriately.
- Opens a terminal page that shows the most recent screenful of output.
If the session was already running, output appears immediately. If you tapped a host that has no live window yet, the watch shows Opening on iPhone… and waits up to eight seconds for the iPhone to acknowledge. After that, you'll see the terminal page or a banner explaining what went wrong.
Get comfortable with the controls
Across the bottom of the terminal page you will see two rows of small buttons. The most important ones for first use:
- Cmd / Text — switches voice dictation between command mode (it interprets phrases like "control b" and "next window") and prose mode (it sends what you said as text).
- Mic — start dictation. Speak, then tap Done.
- Dn / Rd — toggles between Dense and Readable display. Dense fits more rows; Readable is easier on the eyes.
- Keys — opens the on-screen mini keyboard.
- Rpt — reappears once you have sent at least one command from the watch; tapping it re-sends that command.
- Reload (arrow.clockwise) — toggles the iPhone-side connection: useful for reconnecting a dropped session.
Below those, a tmux shortcut bar gives you ^B, :, Det, n, p, %, and " for tmux prefix, command prompt, detach, next/previous window, and vertical/horizontal splits.
Input on watch explains each of these in detail.
Swipe between windows
If your iPhone has more than one open window, swipe left or right on the terminal page to switch between them. The window the watch is showing becomes the iPhone's selected window automatically — that way the iPhone foregrounds the same one you are looking at on your wrist.
Glance, do not stare
The watch is meant for ambient glancing — pull your wrist up, see the last few lines of a build, drop your wrist. The screen turns off after a few seconds of inactivity. When you raise your wrist again, the watch reconnects and brings you back to the same session, with output caught up to the present.
Where to go next
- Pairing with iPhone — what data flows over the relay, and what to do when it stalls.
- Viewing sessions — how the terminal page, swipe, and alerts work.
- Input on watch — typing options: dictation, mini keyboard, tmux shortcuts.
- Troubleshooting — when things are not behaving.