vmuxWatch
A wrist-side viewer and tiny remote for the SSH sessions running on your iPhone.
What vmuxWatch is
vmuxWatch is the Apple Watch member of the vmux family. It is a small, focused companion to vmuxPhone: a wrist-side viewer of the same workspace your iPhone is running, with just enough input to nudge a session forward when you do not want to take the phone out of your pocket.
vmuxWatch is not a standalone terminal. It does not connect to SSH or Mosh hosts on its own; the iPhone does the heavy lifting. The watch shows what the iPhone has, and forwards your taps, dictation, and on-screen key presses back to the iPhone so the phone can apply them to the real session.
What it shows
- The list of saved hosts that your iPhone knows about.
- The list of currently open windows on the iPhone, with each window's title, host label, and connection state.
- A live, character-grid snapshot of the most recent screenful of terminal output for the selected window.
- The current connection state of every window: connected, connecting, disconnected, or failed (with a concise reason).
You can swipe between open windows, switch between a dense and a readable display, and tap a host to ask the iPhone to bring that session forward.
What you can do from the watch
- Tap an open window to focus it on the iPhone and start watching its output.
- Tap a saved host to ask the iPhone to open a window for it.
- Send keystrokes through a built-in mini keyboard with Shift, numbers, symbols, arrows, Tab, Enter, Esc, and Backspace.
- Dictate a command or a piece of prose using the watch microphone, and have the iPhone send it as keystrokes.
- Send tmux shortcuts (prefix, command prompt, detach, next/previous window, vertical/horizontal split) with single-button buttons or by saying their names.
- Reconnect a window that has dropped, or repeat the last command you sent from the watch.
This is enough to babysit a long-running build, restart a service, scroll a tail, or detach a tmux session — without ever picking up the phone.
What it cannot do
- Open SSH or Mosh sessions independently. The iPhone has the keys, the network, and the credentials. The watch is always relayed through the iPhone.
- Show full scrollback. Only the most recent screenful is sent to the watch.
- Operate when the iPhone is unreachable. If the iPhone is far away, powered off, or the Watch app on iPhone has been uninstalled, the watch shows a "Phone not reachable" status and waits.
- Replace vmuxPhone on its own. The watch app refuses to function meaningfully without an iPhone running vmuxPhone in range.
System requirements
| Requirement | Minimum |
|---|---|
| Apple Watch | Series 6 or later (Apple Watch SE 2nd generation works, original SE works but is cramped) |
| watchOS | watchOS 10 or later |
| Paired iPhone | An iPhone running vmuxPhone with at least one host saved |
| Pairing | The Watch must be paired to that iPhone in the standard iOS Watch app |
| Connectivity | Bluetooth between watch and iPhone, or both on the same Wi-Fi network |
vmuxWatch installs automatically when you install vmuxPhone and your watch is paired. If it does not appear, open the Watch app on your iPhone, scroll to Available Apps, and install vmuxWatch from there.
Constraints to keep in mind
- Read-mostly. The watch is best at glancing. The mini keyboard works, but the screen is small and the keys are small. Use dictation for anything more than a few characters.
- Tethered. The watch reaches the iPhone through Apple's
WatchConnectivityframework. When the watch and the iPhone lose contact (different rooms, watch on charger, iPhone Low Power Mode aggressive), updates pause until they reconnect. State catches up as soon as they do. - Battery-aware. The relay is designed to coalesce updates so it does not chew battery on either device. You can still drain the watch faster than usual if you keep the screen on for long periods of terminal output.
- One iPhone per watch. A watch follows the iPhone it is paired with. There is no way to mirror a watch from a different iPhone.
How vmuxWatch fits in the family
| Capability | vmuxWatch | vmuxPhone | vmux on visionOS |
|---|---|---|---|
| Standalone SSH client | No | Yes | Yes |
| Local shell | No | No | No |
| Live terminal output | Yes (last screen) | Yes (full scrollback) | Yes (full scrollback) |
| Type into a session | Mini keyboard, dictation, tmux shortcuts | Full software keyboard | Full hardware or VKeyboard |
| Open a saved host | Yes (via iPhone) | Yes | Yes |
| Multiple windows | View list, swipe between | Yes | Yes (spatial) |
| Notifications | Yes (forwarded by iPhone) | Yes | Yes |
Use the watch to glance and nudge. Use the iPhone for real input. Use Vision Pro or Mac when you have real screen real estate.
Where to go next
- Getting started installs vmuxWatch and walks through your first glance.
- Pairing with iPhone explains the link to vmuxPhone, what data flows, and what to do when the iPhone drops out.
- Viewing sessions covers the session list, the terminal page, swipe navigation, and alerts.
- Input on watch describes typing options: the mini keyboard, dictation, tmux shortcuts, and Repeat.
- Troubleshooting is the place to look when sessions are missing, input does not arrive, or the watch is draining battery.