vmuxWidgets
iPhone Home Screen and Lock Screen widgets that monitor vmuxPhone session alerts and connection status at a glance.
What vmuxWidgets is
vmuxWidgets is the widget bundle that ships with vmuxPhone. Once vmuxPhone is installed, the widget gallery on your iPhone gains a new family of widgets that surface session state directly on the Home Screen, the Lock Screen, and the StandBy display. Each widget watches a saved vmux window — a profile pinned to a specific host — and shows whether that window is idle, alerting, reconnecting, or unavailable, without you having to open the app.
The widget bundle is not a separate download. It installs with vmuxPhone and appears automatically in the iOS widget gallery the next time you open it.
What you can monitor
Every widget you add is bound to one saved window. The window definition includes the host label, an optional subtitle (typically the working directory or session purpose), and the theme colors that vmuxPhone uses for that window. The widget renders in those theme colors so a glance tells you which session is which.
The single widget shipped at launch is the Alert Monitor widget. It shows the window's name, status, last summary line, and a colored indicator that flips to an alert tone when the underlying session has produced an unread alert. See Alert Monitor widget for the full reference.
Available sizes
| Family | Where it lives | What you see |
|---|---|---|
| Small | Home Screen | Window name, status chip, single subtitle line, alert dot. |
| Medium | Home Screen | The same content as Small with larger type, more room for the subtitle, and a slightly larger header. |
Lock Screen and StandBy variants are not part of the v1 release of the Alert Monitor widget. They are tracked for a future update; in the meantime, Live Activities cover the Lock Screen and Dynamic Island.
How widgets fit alongside other vmux surfaces
vmuxPhone already exposes session information in three other places. Widgets complement them rather than replace them.
| Surface | When you use it |
|---|---|
| Live Activities | Active session is connected and you want a Lock Screen or Dynamic Island indicator. |
| Notifications | A session triggers an alert and you want it pushed to your screen. |
| vmuxPhone widgets | Quick host launchers and connection-state widgets that vmuxPhone provides. |
| vmuxWidgets (this manual) | Long-lived per-window monitor that sits on your Home Screen and reflects current state. |
A common setup is to keep vmuxPhone widgets for one-tap host launching and the Alert Monitor widget for the windows you actively babysit, such as a build that emits a notification when it fails or a long-running watch process.
Requirements
| Requirement | Minimum |
|---|---|
| iPhone | iPhone running iOS 17 or later. |
| App | vmuxPhone installed and at least one host configured. |
| Window | At least one saved window so the widget editor has something to choose. |
| Notifications | Enabled if you want the alert dot to react to session events. See the vmuxPhone notifications guide. |
The widget extension shares an App Group with vmuxPhone, so you must be signed in to the same Apple ID and run the same build of vmuxPhone for the widgets to read state.
What data the widget extension can see
Widgets are sandboxed and read state from a small JSON snapshot that vmuxPhone writes to a shared App Group. They can see:
- The list of saved window definitions, each with display name, optional subtitle, status text, and theme colors.
- The current status of each window — idle, alerting, reconnecting, or unavailable.
- A freshness flag — whether the snapshot came from a push notification, a poll, or is stale.
- An optional one-line summary captured at the last refresh.
Widgets cannot see scrollback, terminal output, host credentials, or anything that is not in that snapshot. They have no network access. Tapping a widget opens vmuxPhone to the matching window via a deep link.
Refresh model
iOS gives widgets a daily refresh budget per app. vmuxPhone writes a fresh snapshot whenever its session state changes, and the widget reloads on its next allowed slot. While idle, each widget refreshes about once every five minutes. Push-driven changes are picked up faster because vmuxPhone forces a reload at the moment the snapshot is updated.
There is no manual refresh control on the widget itself. Opening vmuxPhone briefly is the most reliable way to nudge the system into a fresh refresh.
Privacy
Everything the widget shows is computed from on-device state that vmuxPhone has already saved. No host names, statuses, or summaries leave the phone via the widget extension. The widget does not request any permissions of its own beyond what vmuxPhone has been granted.
Where to go next
- Alert Monitor widget — the reference for the only widget shipped at launch.
- Adding a widget — step-by-step instructions for the iPhone widget gallery.
- Troubleshooting — fixes for stale data, missing widgets, and configuration that won't stick.
- vmuxPhone widgets — the broader widget catalog from the host app, including Recent Hosts and Session Status.
- Live Activities — Lock Screen and Dynamic Island indicators for live sessions.