vmuxPhone
A real terminal for iPhone with SSH, Mosh, themes, custom keyboard, Live Activities, widgets, and watch pairing.
What vmuxPhone is
vmuxPhone is the iOS member of the vmux family. It is a fully native iPhone app that runs SSH and Mosh sessions on its own — there is no helper laptop, no cloud broker, and no shared host required. The same GPU-accelerated terminal renderer that powers vmux on Apple Vision Pro draws the screen on your iPhone, so output stays sharp at any zoom level, scrollback feels instant, and CRT effects, glass backgrounds, and theme switching all work the way you expect.
Around that terminal core, vmuxPhone adds the things that make a phone-sized terminal pleasant to use: an embedded software keyboard tuned for shells, a quick-action accessory bar with Ctrl, Alt, Shift, Esc, Tab, and arrow keys, a Files-aware theme importer, Nerd Font support, voice dictation that types into the shell, drag-and-drop image upload over SFTP, push-to-paste, Lock Screen Live Activities for running sessions, Home Screen widgets for one-tap reconnect, and a relay to vmuxWatch so you can see session activity on your wrist.
Highlights
- Saved hosts with a per-host transport choice — SSH, Mosh, vmux, Telnet, ET, and (behind a flag) tmux control mode.
- Secure Enclave SSH keys generated on-device. The private key never leaves the iPhone hardware.
- Mosh roams across cellular, Wi-Fi, and sleep cycles. SSH reconnects automatically after lock and resume.
- Embedded keyboard with optional voice input, swipe-to-type, and a half-and-half landscape layout.
- Edge-pull gesture between active terminal windows — drag from either side of the terminal to switch windows or open a new one.
- Lock Screen Live Activity and Dynamic Island show host, status, last snippet, and an alert badge whenever the bell rings.
- Home Screen and Lock Screen widgets for recent hosts and session monitoring.
- Pairs with Apple Watch over WatchConnectivity for read-only session snapshots and tap notifications.
- Themes are imported from VSCode
.jsonfiles via the Files app. Nerd Fonts are imported through the system font picker. - Background continuity logic keeps the session warm during the iOS background grace period and resumes cleanly when you come back.
System requirements
| Requirement | Minimum |
|---|---|
| iOS | iOS 17 or later. Some surfaces (Liquid Glass terminal toolbar, the latest Live Activity layout) light up only on iOS 26 or later. |
| Devices | iPhone with an A14 chip or newer. Older devices are not supported. |
| Disk | About 80 MB. Themes and fonts add a few MB each. |
| Network | Required for any remote session. Local-only vsh commands work offline. |
| Optional | An Apple Watch running watchOS 10 or later for the vmuxWatch companion. |
vmuxPhone is sandboxed and ships through the App Store. The phone-side bundle is app.vmux.phone.
How vmuxPhone compares
| Feature | vmuxPhone | vmux (visionOS) | vmuxMac |
|---|---|---|---|
| Local shell | No | No | Yes |
| SSH | Yes | Yes | Yes |
| Mosh | Yes | Yes | Yes |
| Multi-window | Yes (edge-pull canvas) | Yes (spatial) | Yes (Mac windows) |
| Embedded keyboard | Yes | VKeyboard (spatial) | Hardware keyboard |
| Voice input | Yes | Yes | No |
| Live Activity | Yes | No | No |
| Lock Screen widget | Yes | No | No |
| Watch companion | Yes | No | No |
| Optic / Touch / Face ID lock | Face ID | Optic ID | Touch ID |
| CRT and glass effects | Yes (post-process overlay) | Yes (Metal pipeline) | Off (paused on macOS) |
vmuxPhone is the right answer when you are away from your desk and want a real terminal that fits in your pocket. Use vmux on visionOS for spatial terminals at home, and vmuxMac at the desk.
What is different from vmux on Vision Pro and Mac
A few things behave differently on iPhone:
- Single connection per window. vmuxPhone uses one PTY per window. To run more than one session, use the edge-pull gesture or the Sessions canvas to add another window. Splits inside one window are only available when you connect through the vmux multiplexer or tmux control mode.
- Embedded keyboard, not VKeyboard. The on-screen keyboard is a custom view that lives at the bottom of the terminal in portrait and on both sides in landscape. There is no spatial floating keyboard.
- Mosh does extra work in the background. iOS background time is short. vmuxPhone's
IOSBackgroundTaskCoordinatorkeeps the connection warm for the grace period the system grants, then suspends gracefully and resumes on foreground. - Live Activities replace the desk widgets. Active sessions show up on the Lock Screen and in the Dynamic Island instead of in a desktop dock.
- Watch relay. A paired Apple Watch sees the same workspace through vmuxWatch, with read-only snapshots and tap-to-foreground.
Where to go next
- Getting started — install, launch, and add your first host.
- Connecting — SSH, Mosh, key auth, and the connection form.
- Terminal display — renderer, CRT effects, glass, and cursor styles.
- Keyboard and input — software keyboard, hardware keyboards, gestures, and voice.
- Accessory bar — every button on the quick-action strip.
- Mosh on iPhone — backgrounding, reconnect, and auto-run runs.
- Live Activities — the Lock Screen and Dynamic Island indicator.
- Widgets — Home Screen and Lock Screen widgets.
- SSH key manager — Secure Enclave key lifecycle.
- Workspace — host list, sessions canvas, and breadcrumb navigation.
- Themes and fonts — the picker, VSCode imports, and Nerd Fonts.
- Watch pairing — what data flows to vmuxWatch.
- Notifications — what the bell, command-completed, and disconnect alerts look like.
- Troubleshooting — fixes for the most common issues.