Enabling Live Activities
System and per-app switches that control whether vmuxPhone publishes a Live Activity, plus auto-start and stop rules.
What you need to turn on
There are two switches between you and a working Live Activity. Both have to be on, and they live in different places in iOS Settings. If either one is off, vmuxPhone may attempt to publish an activity but iOS rejects the request and nothing appears on the Lock Screen or in the Dynamic Island.
System switch
Open Settings → Face ID & Passcode (or Touch ID & Passcode on older models). Enter your passcode. Scroll to the Allow Access When Locked group and ensure Live Activities is on. This is a global iOS setting that affects every app, not just vmuxPhone. If it is off, no app can publish Live Activities while the iPhone is locked.
Per-app switch
Open Settings → vmux → Live Activities and turn the toggle on. This switch is created by iOS automatically when vmuxPhone is installed and ships an ActivityKit extension. If the switch is missing, the most likely reason is that vmuxPhone has not been launched at least once. Open vmuxPhone, connect to a host, then return to Settings — the switch will be there.
There is no in-app toggle inside vmuxPhone. The per-app switch is the only place to disable Live Activities for vmux specifically.
When vmuxPhone starts an activity
vmuxPhone starts a Live Activity automatically. You do not have to do anything. The rules that govern when an activity appears are deliberately strict to avoid noise:
- An activity starts on a successful connect. Pre-connect states like Connecting… and Mosh bootstrap… stay inside the app — they are too short-lived to deserve their own Live Activity.
- One activity is created per connected session. If you have two windows connected to two different hosts, you get two activities.
- The activity updates whenever something meaningful changes — output arrives, the connection state changes, the bell rings, or iOS moves the app between foreground and background.
- Updates are coalesced to roughly every 2 seconds while the session is active. iOS imposes its own budget on top of that, so a noisy session does not burn through the daily update allotment.
Because the activity is created on a real connection, you cannot use it as a "this session is about to start" indicator. It is a status surface for sessions that are already alive.
When vmuxPhone ends an activity
Activities end immediately when the underlying session is no longer running:
- On a clean disconnect, the activity ends at once. There is no lingering "session ended" banner.
- On a connection failure, the activity ends with the failure reason in the status field, then disappears shortly after.
- On force-quit of vmuxPhone, the activity ends — iOS reaps activities owned by terminated apps.
- If iOS suspends the vmuxPhone runtime for too long while you are away, the activity may freeze at its last state until the app foregrounds again. Reopening vmuxPhone refreshes or ends the activity.
You do not stop activities yourself. There is no "Stop Live Activity" button inside vmuxPhone today. If an activity is stuck, see troubleshooting.
Auto-start versus manual start
vmux is auto-start only. Connecting a session is the trigger; there is no menu item that says "publish a Live Activity for this session." This matches Apple's recommended Live Activity model — activities should reflect a real, currently-running task, not a passive notification.
The closest you have to manual control is:
| What you want | How to do it |
|---|---|
| Start an activity for a session | Connect that session in vmuxPhone |
| Stop an activity early | Disconnect the matching session |
| Pause activities globally for vmux | Toggle Settings → vmux → Live Activities off |
| Pause Live Activities across all apps | Toggle Settings → Face ID & Passcode → Allow Access When Locked → Live Activities off |
| Re-publish a frozen activity | Force-quit vmuxPhone and reconnect the session |
What changes when you toggle the switch
Turning the per-app switch off while a session is connected does not retroactively remove the existing activity — iOS continues showing it until the session disconnects or the activity hits its iOS-imposed lifetime. New activities, however, are not allowed to start. Turning the switch back on lets the next connect publish a fresh activity. There is no need to relaunch the app.
The system switch behaves the same way: existing activities keep displaying on the Lock Screen until they end, but new ones cannot start while the switch is off.
What you cannot do
A few things are not possible by design:
- You cannot publish a Live Activity for a disconnected session. If you want a "host is offline" indicator, use the Widgets surface instead, which is designed for ambient state.
- You cannot schedule a future Live Activity. Activities are tied to a real, running session. There is no "remind me in 10 minutes" mode.
- You cannot share an activity across devices. The Live Activity belongs to the iPhone that holds the session. iPad, Mac, and Apple Watch do not see it. The Apple Watch surface is covered separately under vmuxWatch.
- You cannot interact with the activity. There are no buttons today. Tapping it opens vmuxPhone with the matching session selected. A future release may add reconnect or disconnect actions via App Intents.
Related
- Dynamic Island — the compact, minimal, and expanded layouts.
- Lock Screen presentation — what the Lock Screen card shows.
- Troubleshooting — when the activity does not appear.
- vmuxPhone — Live Activities — the in-app rules from the parent manual.
- vmuxPhone — the source of session lifecycle events.