Getting Started
Install vmuxPhone, set up biometric unlock, add your first host, and connect.
Install
vmuxPhone ships through the App Store. Search the App Store for vmux, install the iPhone app, and tap Open when the install completes. The app is sandboxed; it does not need any system-wide permissions to draw the terminal or connect over SSH.
If you also use vmux on Vision Pro, vmuxMac, or own RemoteSignerPhone, install those separately. vmuxPhone runs on its own and does not require any of them.
First launch
The first time you open vmuxPhone you land on the host list with the title vmux at the top and an empty state that reads No Hosts Yet — Add an SSH or Mosh destination to start a terminal session. There are two sections on this screen:
- Saved Hosts — every connection you save will appear here.
- Security — a single row that opens the Device Key screen for managing the Secure Enclave SSH key on this iPhone.
A + button in the top-right opens the host editor. Use that to add the first connection.
Permissions
iOS asks for a few permissions the first time vmuxPhone needs them. Each one is optional and the app falls back gracefully when you decline.
| Permission | Asked when | Why vmuxPhone wants it |
|---|---|---|
| Notifications | First launch | Bell, command-completed, and disconnect alerts when the app is in the background. |
| Microphone | First time you tap the voice button on the embedded keyboard | Dictation that types into the active shell. |
| Speech Recognition | Same as above | Converts mic audio to text on-device when possible. |
| Local Network | First connection to a .local host | Lets vmuxPhone discover Bonjour names like mac-mini.local. |
| Camera | Only if you enable camera passthrough in Appearance | Renders the rear camera behind the terminal as a productivity overlay. |
Decline any of these and the corresponding feature simply turns off. You can flip them back on later in Settings → vmux.
Set up biometric unlock
vmuxPhone does not lock the app behind Face ID by default — you can choose to. Open the host editor, then tap the gear icon (or open Appearance) and turn on App Lock. Once enabled, the app requires Face ID (or Touch ID on supported iPhones) every time it returns from the background.
Face ID also gates the Secure Enclave SSH key when a remote host requests a signature with that key, even if App Lock is off. Each signing operation is approved separately so that a stolen unlocked phone still cannot impersonate you.
Add your first host
Tap the + button on the host list. The New Host form opens with these sections:
Destination
| Field | What to enter |
|---|---|
| Label | A friendly name like home or prod-bastion. Optional but recommended. |
| Host | Hostname or IP. Examples: dev.example.com, 192.168.1.10, mac-mini.local. |
| Port | Defaults to 22. Change it for non-standard SSH ports. |
| Username | The user you log in as on the remote host. |
| TERM | The TERM value sent to the remote shell. Default is xterm-256color. |
Authentication
A segmented control switches between Password and Device Key:
- Password — you type the password into the Password field. It is stored in the iOS Keychain.
- Device Key — vmuxPhone uses the Secure Enclave SSH key on this iPhone. You must add the matching public key to
~/.ssh/authorized_keyson the server. See SSH key manager.
Transport
Pick one. The settings below the picker only appear for the relevant transport.
| Transport | When to pick it |
|---|---|
| SSH | Default. Works everywhere. |
| Mosh | Better for cellular and roaming. Requires mosh-server on the remote. See Mosh on iPhone. |
| vmux | Connect through a running vmuxd daemon for tabs and panes. |
| Telnet | Plaintext Telnet. Use only on trusted networks. |
| ET | Eternal Terminal — drop-in SSH alternative with reconnect. |
| tmux | Hidden behind a feature flag today. Will become a first-class option in a future release. |
Tap Save in the top-right when the form is complete. The new host appears in the Saved Hosts section.
Connect
Tap the host row. The terminal view opens with the embedded keyboard at the bottom (in portrait) or as a left-and-right rail (in landscape). vmuxPhone establishes the SSH or Mosh connection automatically as soon as it knows the terminal size, which happens within the first frame.
You will see one of these states in the status line:
- Connecting to host… — the SSH handshake is in progress. Authentication takes a few seconds.
- Maintaining connection in background… — the app went to the background; the OS-granted grace timer is running.
- Session paused in background. — the grace period ran out; the connection will resume when you bring vmuxPhone back to the front.
- Reconnecting… — vmuxPhone is reattaching after a network change or background return.
The terminal renders as soon as the shell prints its first prompt. Type into the embedded keyboard, the accessory bar, or a connected hardware keyboard.
Edit, duplicate, or delete a host
On the host list, swipe a row leftward. Two actions appear:
- Edit — re-opens the form with the existing values prefilled. Saving updates the row in place.
- Delete — removes the host. The matching Keychain password is removed too.
To duplicate a host, edit it, change the label and any other fields, and save. There is no explicit duplicate command yet.
Connect from elsewhere
Three more entry points open the same terminal:
- vmuxWidgets — tap a recent-host widget on the Home Screen or Lock Screen. See Widgets.
- Live Activity tap — tapping the Lock Screen or Dynamic Island indicator brings the matching session forward. See Live Activities.
- Apple Watch — if vmuxWatch is paired, tapping a session on the watch foregrounds it on the iPhone.
What to read next
- Connecting — full reference for the connection form and the auth methods.
- Workspace — the multi-window layout, sessions canvas, and edge-pull gesture.
- Keyboard and input — embedded keyboard, hardware keyboards, voice input, and gestures.