Troubleshooting

Keyboard does not appear

The embedded keyboard is part of vmuxPhone — it is not the system keyboard. If it disappears unexpectedly:

• Check the menu. Open the round menu in the terminal toolbar. If you see Show Keyboard, the keyboard is hidden. Tap to bring it back. The small floating "keyboard" bubble next to the menu also restores it with one tap.
• Hardware keyboard connected. If a Magic Keyboard or other Bluetooth keyboard is paired, vmuxPhone hides the embedded keyboard automatically. Disconnect the hardware keyboard to bring the embedded one back.
• Force-quit and re-launch. A handful of UIKit edge cases cause the keyboard to lose its first-responder grip. A clean restart fixes this.

If you are looking for the system keyboard (with QuickType and your custom user keyboards), it is not used inside vmuxPhone. The terminal renders the embedded keyboard exclusively. The vmux keyboard extension is a different surface — it is a system-wide keyboard that you turn on in Settings → General → Keyboard → Keyboards. See Keyboard extension.

Cannot connect — Permission denied (publickey)

You picked Device Key but the public key is not authorized on the remote host.

1. Open Security → Device Key on vmuxPhone.
2. Tap Copy Public Key.
3. SSH to the host using a different method (password, or a desktop client) and append the line to ~/.ssh/authorized_keys.
4. Verify file modes: ~/.ssh is 0700, authorized_keys is 0600, both owned by your remote user.
5. Reconnect with Device Key auth.

If the iPhone restored from a backup or you reinstalled iOS, the Secure Enclave key has been re-generated and the previous public key is now orphaned. Generate a new key and re-authorize.

Cannot connect — Connection refused or Operation timed out

• Wrong port. Confirm the Port in the host editor. Default 22.
• Wrong host. Bonjour names like mac-mini.local need iOS Local Network permission. Settings → vmux → Local Network must be on.
• Firewall. A firewall on the remote network or host may be blocking the connection. Test from a desktop client to confirm.
• Carrier blocking. Some carriers block outbound port 22. Switch to Wi-Fi to test, or use Mosh on a non-default port.

Mosh disconnects

Repeated Mosh disconnects on iPhone are almost always one of these.

See Mosh on iPhone for the full lifecycle reference.

Sessions do not resume after backgrounding

vmuxPhone restores connections automatically when you bring the app forward. If they do not resume:

• Wait a few seconds. The status line should change from Session paused in background to Reconnecting… to Connected within ~10 s.
• Tap Reconnect. From the round menu, pick Reconnect. This forces a fresh handshake.
• Force-quit and re-launch. vmuxPhone restores the host list and window list on launch, but always starts each session disconnected. A clean launch is the simplest reset.
• Check connectivity. If the iPhone has no network access, no resume is possible.

If the session restores but the scrollback is empty, that is expected: scrollback is per-session and does not persist across full app restarts. Only Mosh in-flight buffers survive a background suspension; an actual app process death always loses scrollback.

Watch is not connecting

• Confirm pairing. In the Watch app on iPhone, the watch must be paired and active.
• Confirm vmuxWatch is installed. Watch app → My Watch → Available Apps lists watch apps. Install vmuxWatch if it is missing.
• Open vmuxPhone. The relay activates on the first workspace event. With no hosts saved, there is nothing to send.
• Wait a beat. The first sync after install takes a few minutes for iOS to propagate the app catalog.
• Restart both apps. Force-quit vmuxPhone and the watch app, then re-open both.

If the watch shows stale data, it is usually a WatchConnectivity lag — the relay catches up on next watch wake. See Watch pairing.

Live Activity is stuck

• Disconnect / reconnect the matching session. The activity is created on connect and ended on disconnect; re-creating it fixes most stuck states.
• Force-quit and re-launch vmuxPhone. iOS may have lost the activity end notification.
• Restart the iPhone. A reboot clears the entire ActivityKit state if a stale activity refuses to dismiss.
• Verify the system switch. Settings → Face ID & Passcode → Allow Access When Locked → Live Activities must be on for activities to appear at all.

See Live Activities for the publishing rules.

Push notifications missing

vmuxPhone does not use push notifications; everything is local. So "missing push notifications" means the local notifications are missing.

• Settings → vmux → Notifications. Toggle Allow Notifications off, then back on.
• Show Previews. Set to Always if you want the host label and body on the Lock Screen.
• Focus mode. Check that no Focus mode is silencing vmuxPhone notifications.
• Foreground rule. Bell notifications are suppressed when vmuxPhone is in the foreground; they only fire when the app is in the background or the screen is locked.
• Bell throttle. Bells are throttled to 1 per 5 s per session. Bursts coalesce.

For command-completed notifications, you also need shell integration installed on the remote. Without it, command-completed events never fire.

Voice input is not transcribing

• Microphone permission. Settings → vmux → Microphone must be on.
• Speech recognition permission. Settings → vmux → Speech Recognition must be on.
• iOS dictation language. Speech recognition uses the iOS system language. Set a supported one.
• Check voice mode. The keyboard's voice section has a Cmd / Prose / Off picker. Off disables transcription entirely.

If the agent voice flow is not getting your reply, watch the keyboard transcript area — vmuxPhone shows "Listening…" while the mic is open and "Listening timed out" if you did not speak within the configured silence threshold.

Image upload fails

• Connect first. Drag-and-drop only works on connected sessions. Connect, then drop.
• One at a time. vmuxPhone serializes uploads. The progress overlay tells you how many remain.
• Connection drop mid-upload. The image lands on the remote, but the paste is suppressed. Tap the alert that appears for the remote paths, then paste them yourself when the session reconnects.

Theme picker shows no themes

A first-launch race can put the theme store in a transient empty state. Force-quit and re-launch vmuxPhone — the bundled themes always rehydrate on launch. Imported .json files in On My iPhone → vmux appear after the first picker open.

Diagnostic logs

vmuxPhone writes two diagnostic surfaces you can hand off to support:

• Cache log — Caches/vmux-markers.log inside the app sandbox. Auto-run lifecycle markers and a few critical events get appended here. Accessible via Files → On My iPhone → vmux → Caches when File Sharing is enabled in the build configuration.
• Console log — visible in Xcode if you have the device tethered, under the app.vmux.phone subsystem.

When you file a bug, attach a screen recording of the issue plus the cache log if you can reach it. If the issue happened during a Mosh run, also include the Settings → vmux → Diagnostics → Export Diagnostics report — the same report the visionOS app produces.

Related

• Connecting — the host editor and authentication.
• Mosh on iPhone — backgrounding and reconnect.
• Live Activities — Lock Screen indicator.
• Notifications — local alert rules.
• Watch pairing — relay diagnostics.