Widgets
Home Screen and Lock Screen widgets for recent hosts and session monitoring.
What you get
vmuxPhone ships a widget extension with several configurable widgets. They live on the Home Screen, the Lock Screen, and (on iPhones that support StandBy) on the StandBy display. Widgets are read-only — they show information and tap to open the matching surface in vmuxPhone.
The widget extension is part of the vmuxPhone install. There is no separate download.
Available widgets
| Widget | Sizes | What it shows |
|---|---|---|
| Recent Hosts | Small, medium, large, and inline | A list of your saved hosts with one-tap connect. The small variant shows the most recent host; the medium and large variants show several. |
| Session Status | Small, medium, and circular complications | The connection state of an active session — Connected, Reconnecting, Paused, or Disconnected — and the host label. |
| Lock Screen pill | Inline | A single line that toggles between the most recent host and the most recent activity timestamp. |
| StandBy | Large landscape | A horizontal layout with the active host name, the working directory, and a colored status dot. |
The exact catalog evolves with each release. The list above describes the v1 launch widgets.
Add a widget
On the Home Screen or Lock Screen:
- Long-press the wallpaper or an existing widget until icons start to jiggle.
- Tap the + button in the top-left.
- Search for vmux.
- Pick the widget and the size, then tap Add Widget.
- Tap Done to leave editing mode.
To configure a widget after it lands, long-press it and pick Edit Widget. The editor shows widget-specific options like which host the Recent Hosts widget should pin or which session the Session Status widget should monitor.
Tap behavior
Tapping a widget always opens vmuxPhone with the most useful state given the widget's purpose:
- Recent Hosts — opens the matching host's terminal. If a session is already alive for that host, vmuxPhone selects it; otherwise it starts a new connection.
- Session Status — selects the matching session and brings the keyboard up.
- Lock Screen pill — opens vmuxPhone to the host list. Face ID runs if App Lock is on.
- StandBy — opens vmuxPhone to the active session.
The Lock Screen and StandBy variants honor App Lock — if you have Face ID lock enabled, iOS asks for it before unhiding the terminal.
What data the widget extension can see
The extension is sandboxed and shares an app group with vmuxPhone. It reads:
- Saved hosts and their labels (no passwords).
- The most recent session list with host labels and connection state.
- The most recent activity timestamp per session.
It does not read scrollback or terminal output. It does not have network access. Everything the widget shows is computed from data that vmuxPhone has already saved on the device.
Refresh frequency
iOS budgets widget refreshes per app. vmuxPhone tries to refresh widgets:
- On every connect, disconnect, and connection-state change.
- Every few minutes while a session is alive (subject to the iOS budget).
- Whenever you launch vmuxPhone (the next refresh slot is reserved on app exit).
There is no manual refresh button. If a widget looks stale, opening vmuxPhone briefly will trigger a refresh.
Permissions
The widget extension does not request any permissions beyond what vmuxPhone itself has. Notifications, microphone, and camera are not used by the widget code path.
Disabling widgets
To remove a widget, long-press it and pick Remove Widget. To suppress all vmuxPhone widgets temporarily, you can hide the entire app group from the widget gallery via Settings → Screen Time → Content & Privacy Restrictions → Allowed Apps — though most users simply remove the widgets they do not want.
Troubleshooting
Widgets show No data yet
This appears the first time after install, before vmuxPhone has saved any hosts or sessions. Open vmuxPhone, add at least one host, connect once, and the widgets populate within a few seconds.
Widget keeps showing Disconnected for a Mosh session that is paused
The widget reflects the session state stored on disk; if vmuxPhone is suspended and cannot update the shared store, the widget can lag. Foregrounding the app once writes the latest state and refreshes the widget.
Tap does nothing on the Lock Screen
App Lock is asking for Face ID under the lock UI. Look down at the bottom of the Lock Screen — the Face ID prompt appears below the widgets, and the tap completes after authentication.
Widget never refreshes
iOS budgets widget refreshes aggressively. If a session has been idle for a long time, the timeline can extend to many minutes between refreshes. Open vmuxPhone briefly to force a refresh slot.
Related
- Widgets manual — the family-wide widget reference.
- Live Activities — Lock Screen and Dynamic Island indicators for active sessions.
- Workspace — the in-app surface that widget taps lead to.