Adding a widget

Before you start

Make sure vmuxPhone is installed and that you have at least one saved host with a window pinned to it. The widget editor lists windows from a shared snapshot that vmuxPhone writes when you save them. With no windows saved, the Window picker is empty and the widget shows a placeholder.

If you have not set up any windows yet, open vmuxPhone, connect to a host, and let the session settle into a window definition. See the vmuxPhone workspace for how windows are organized.

Add a widget to the Home Screen

1. Long-press an empty area of the Home Screen until the icons start to jiggle.
2. Tap the + button in the top-left corner. The widget gallery opens.
3. Search for vmux. The vmuxWidgets bundle appears alongside vmuxPhone's own widgets.
4. Pick the Window widget — this is the Alert Monitor.
5. Swipe between the Small and Medium previews and choose the size.
6. Tap Add Widget.
7. The widget lands on the Home Screen with a placeholder. Tap Done to leave editing mode, or skip ahead to Choose the window below to bind it before you exit.

Choose the window

Newly placed widgets default to no window. They render a neutral placeholder until you bind one. To bind:

1. Long-press the widget on the Home Screen.
2. Pick Edit Widget.
3. Tap the Window row.
4. Pick the saved window you want to monitor. The list is populated from vmuxPhone's snapshot.
5. Tap outside the editor or press Done.

The widget redraws within a few seconds in the chosen window's theme colors. If the picker is empty, see Troubleshooting.

Add to the Lock Screen

The launch release of the Alert Monitor widget supports the Home Screen only. The widget gallery on the Lock Screen will not list it.

For Lock Screen visibility, use the vmuxPhone-bundled Lock Screen widgets at vmuxPhone widgets, or pin a Live Activity to the Lock Screen for the duration of an active session — see Live Activities.

Lock Screen and StandBy support for Alert Monitor are tracked for a future release.

Add to StandBy

StandBy widgets are not supported in the launch release. The same guidance as the Lock Screen applies: vmuxPhone's bundled widgets and Live Activities cover the gap until Alert Monitor adopts those families.

Add multiple widgets

Each Home Screen widget instance is independent. Repeat the steps above to add another instance and bind it to a different window. Common patterns:

• Two small widgets side by side. One watches a build server, the other watches a long-running watcher. Both alert independently.
• One medium widget in a prominent slot. The widget you most need to see — the one that fires the most actionable alerts — gets center stage.
• Stacked widgets. iOS supports stacking widgets of the same size. Drop several Alert Monitor widgets into a Smart Stack and let iOS rotate based on which one updated most recently.

There is no built-in limit on instances. iOS budgets refresh slots across all of them, so adding many widgets does not give each one a faster refresh.

Edit the size after adding

iOS does not let you switch a widget between Small and Medium without removing and re-adding it. To resize:

1. Long-press the widget.
2. Tap Remove Widget.
3. Add a fresh widget at the new size and bind it to the same window.

The widget editor does not preserve a previous binding across removal — you will need to pick the window again.

Remove a widget

1. Long-press the widget.
2. Tap Remove Widget.
3. Confirm.

Removing a widget does not affect the underlying window in vmuxPhone. The session keeps running and any other widgets bound to the same window continue to refresh.

Reorder widgets

Long-press the widget and drag it to a new position. The widget keeps its window binding, theme, and refresh state across the move.

Smart Rotate and Smart Stacks

iOS Smart Stacks rotate visible widgets based on context. When you place an Alert Monitor widget into a stack, iOS will surface it preferentially if the underlying window has an unread alert. You do not configure this; iOS handles it from the freshness flag in the snapshot.

If you do not want Smart Rotate to lift the widget unexpectedly, place the widget outside a stack.

Migrating between iPhones

When you restore a new iPhone from an iCloud backup, the Home Screen layout — including widget placements and bindings — restores along with it. The widget bindings reference window IDs from vmuxPhone's snapshot, so the bindings only resolve once vmuxPhone has been launched on the new device and has rebuilt its snapshot. If a widget shows a placeholder after restore, opening vmuxPhone once is the fix.

Related

• Alert Monitor widget — what each visual element means.
• Troubleshooting — fixes when the gallery is empty or the picker has no windows.
• vmuxPhone workspace — where saved windows come from.
• vmuxPhone widgets — the broader catalog of widgets that ship with vmuxPhone.