Keyboard and Input
Software keyboard, hardware keyboards, gestures, and voice dictation on vmuxPhone.
The embedded keyboard
vmuxPhone replaces the system keyboard with a custom view designed for shell work. It lives at the bottom of the terminal in portrait, and on both sides of the terminal in landscape. You always see a function row, modifier toggles, the alphanumeric grid, and the accessory bar.
The embedded keyboard has its own theme that follows the active terminal theme. It also has its own swipe-to-type input system, voice dictation, and a Liquid Glass background on iOS 26 or later.
Layout modes
The keyboard switches layout based on orientation and width.
| Mode | When | What it shows |
|---|---|---|
| Full | Portrait | Standard QWERTY plus function row, modifier row, voice button, and the accessory bar. |
| Left half | Landscape, on the left rail | The left half of the keyboard. |
| Right half | Landscape, on the right rail | The right half plus the voice controls. |
In landscape the terminal sits between the two halves and the rails are sized to a fraction of the screen width (24% by default). This is the layout the iPhone defaults to in landscape; you do not have to do anything to enable it.
Show, hide, and resize
The terminal toolbar menu has a Hide Keyboard / Show Keyboard button. When the keyboard is hidden, the terminal expands to use the entire screen. A small floating "show keyboard" bubble appears next to the menu so you can bring the keyboard back without going through the menu.
In portrait, you can drag the divider between the terminal and the keyboard up or down to resize. The drag is bounded between roughly a quarter and two-thirds of the screen height. The position persists across launches.
Modifier toggles
The keyboard has Ctrl, Alt, Shift, and Fn toggles. Each one is sticky — tap it once to arm and once again to disarm. The next regular key combines with the armed modifier; sticky behavior across multiple regular keys is also supported.
The same toggles also appear on the accessory bar. Either set turns green when active. See Accessory bar for the full reference.
Function keys
The function row exposes F1 through F12 plus standard navigation keys. Function keys are hidden by default when Fn is inactive — turn on Fn from the modifier row to reveal them, then tap the key. The row collapses again when Fn deactivates.
Voice input
A microphone button on the keyboard starts iOS speech recognition. vmuxPhone sends transcribed text into the active shell as it is recognized. Three modes change how the dictation behaves:
| Mode | Behavior |
|---|---|
| Cmd | Inserts text without auto-punctuation, suitable for shell commands. |
| Prose | Adds punctuation and capitalization, suitable for git commit messages. |
| Off | Microphone disabled. |
Voice input also handles the special case of an agent question — when a remote tool sends a __VMUX_ASK__ request, vmuxPhone speaks the prompt aloud, listens for a spoken answer, and either replies through a remote file path or pipes the answer into the shell. The keyboard surfaces this as a separate transcript area whenever the agent flow is active.
Hardware keyboards
vmuxPhone supports any keyboard iOS recognizes — the Magic Keyboard for iPad / iPhone, Bluetooth keyboards, and folio cases that emulate a keyboard. Once a hardware keyboard is paired, plug it in (or pair it) and the system stops showing the embedded keyboard automatically.
Key behavior on a hardware keyboard:
- All printable keys work as expected.
- Modifier keys are passed through. Option can be sent as Meta — the Option as Meta toggle is in the visionOS settings, and the iPhone follows the same rule.
- Cursor keys, page up/down, and function keys behave as on a desktop terminal.
- Cmd shortcuts (Cmd+C, Cmd+V) interact with the system clipboard.
- Pinch on a paired Magic Trackpad zooms the terminal font in single-step increments. The same gesture works on the touchscreen with two fingers.
When the hardware keyboard goes away, the embedded keyboard re-appears within a frame. There is no setting to choose between the two — vmuxPhone picks based on what is connected.
Touch gestures
The terminal surface accepts a small set of gestures. They are the same as the visionOS app where it makes sense.
| Gesture | What happens |
|---|---|
| Tap | Move the cursor focus to the terminal and dismiss the menu. |
| Two-finger pinch | Zoom the terminal font in or out by single steps. |
| One-finger drag | Scroll the scrollback. The renderer pulls cells from ScrollbackBuffer. |
| Double-tap-and-drag | Begin a text selection. Drag to extend; release to copy. |
| Long press | Open the system context menu for paste. |
| Edge drag from leading edge | Pull-to-switch to the previous window in the workspace; or, if you are at the start of the list, open the New Window picker. |
| Edge drag from trailing edge | Same, but to the next window or the New Window picker. |
The edge-pull gesture has visual previews and a commit threshold of about 84 pt of travel. Below that threshold the gesture animates back to the current window. Above the threshold the workspace switches and the new window slides into place.
Entering Esc, Tab, arrows, and symbols
The accessory bar above the keyboard contains every key you need that the alphanumeric grid does not have:
- Esc and Tab — direct keys.
- Up / Down / Left / Right — single-tap arrows. Hold to repeat.
- Pipe
|, slash/, tilde~, dash-— common shell symbols you do not want to dig through layers for.
If you need the rest of the symbol set, the alphanumeric grid has a numbers / symbols layer that toggles with the 123 key, exactly like the system keyboard.
Paste from the system clipboard
Long-press the terminal and pick Paste. iOS may show the clipboard preview banner the first time. To paste a screenshot or image, drop it onto the terminal — vmuxPhone uploads it via SFTP and pastes the remote path. See Terminal display for upload details.
Bracketed paste
vmuxPhone wraps pasted content in bracketed-paste markers when the remote shell asks for it. Inputs from voice dictation, the embedded keyboard, the accessory bar, and Cmd+V from a hardware keyboard all flow through the same bracketed-paste path so multi-line pastes do not trigger early command execution.
Local echo prediction
While typing, vmuxPhone predicts likely characters and renders them immediately, then reconciles when the SSH server responds. On Mosh sessions the Mosh prediction setting controls whether predictions show up.
Related
- Accessory bar — every button on the quick-action strip.
- Workspace — what the edge-pull gesture switches between.
- Mosh on iPhone — local echo on Mosh.