Troubleshooting

Live Activity did not start

If you connected a session in vmuxPhone and nothing appeared on the Lock Screen or in the Dynamic Island, walk through these steps in order.

Verify both switches are on

Two switches must be on. Open Settings → Face ID & Passcode (or Touch ID & Passcode), enter your passcode, and check that Live Activities under Allow Access When Locked is on. Then open Settings → vmux → Live Activities and confirm the per-app toggle is on. If either is off, no Live Activity will appear no matter what vmuxPhone does. See Enabling Live Activities for the full path.

Confirm the session is actually connected

vmuxPhone publishes the activity on a successful connect, not on Connecting… or Mosh bootstrap…. Wait until the in-app status line says Connected. If it never reaches Connected, the activity will not start — fix the connection first using vmuxPhone troubleshooting.

Check the per-app switch is present

If Settings → vmux does not have a Live Activities row at all, iOS has not yet registered vmuxPhone's Live Activity extension. Launch vmuxPhone once, connect to any host, then return to Settings. The row will be there.

Force-quit and relaunch

Swipe up to the App Switcher and dismiss vmuxPhone. Reopen it and reconnect. iOS sometimes loses the activity registration after major updates or storage cleanups; relaunching restores it.

Reboot the iPhone

If the per-app switch is on, the system switch is on, the session is connected, and the activity still does not appear, restart the iPhone. ActivityKit registration occasionally gets wedged after long uptime windows. A reboot resets the system-side registry.

Live Activity stuck after the session ended

You disconnected the session — or vmuxPhone crashed — and the Live Activity is still on the Lock Screen.

Reconnect the same session

Connect to the same host again. vmuxPhone reuses the same session identity, sees the existing activity, and ends or refreshes it on the next state change. This is the gentlest fix.

Force-quit vmuxPhone

Swipe up from the App Switcher, find vmuxPhone, and swipe it away. iOS reaps any activities owned by terminated apps. The stuck card disappears. Relaunch and reconnect.

Wait it out

iOS imposes a maximum lifetime on every Live Activity (eight hours of foreground content, twelve hours of stale content as of iOS 17). Even if vmuxPhone never explicitly ends the activity, iOS reaps it on schedule. If you do not need to use the iPhone, leave it alone for a few hours.

Live Activity does not update

The card appeared but the host name, status, or snippet is not changing despite output arriving in the terminal.

Foreground vmuxPhone briefly

Open vmuxPhone, look at the matching session, then return to the Home Screen. This forces the activity to refresh on the next state change. ActivityKit suspends background updates aggressively when the app has been out of view for a long time.

Check that the session is still connected

If the in-app status line shows Reconnecting… or Disconnected, the activity is reflecting reality — there is no new output to display. Reconnect first.

Wait for the rate limit window

Live Activity updates are coalesced to roughly every two seconds while a session is active. A rapid burst of output may visibly lag in the activity. The lag is intentional and recovers within a couple of seconds.

Restart vmuxPhone

If the activity has been frozen for several minutes and the session is still connected, force-quit vmuxPhone and reconnect. iOS may have suspended the background runtime that pushes updates into the activity. Reconnecting publishes a fresh activity in a fresh runtime.

Dynamic Island missing on this iPhone

The Lock Screen card works but the Dynamic Island never shows anything.

Check your iPhone model

Only iPhone 14 Pro, 14 Pro Max, and every iPhone 15 / 16 / 17 model have a Dynamic Island. iPhone 14 (non-Pro), iPhone SE, and every iPhone before iPhone 14 Pro do not have the hardware. The Lock Screen card is the only Live Activity surface on these models.

Foreground another app

The Dynamic Island only renders Live Activities while the owning app is in the background. If vmuxPhone is in the foreground, iOS hides the cutout indicator because the same content is already on screen. Switch to another app and the Dynamic Island will appear.

Look for the minimal state

If multiple apps have Live Activities open, vmux may be in the minimal state — a single dimmed terminal glyph in the cutout. Tap the cutout to switch which activity is in front. iOS rotates focus, vmux does not pick.

Settings switch missing

You opened Settings → vmux and there is no Live Activities row.

Launch the app once

iOS only adds the per-app Live Activities switch after the app has launched at least once and registered its ActivityKit extension. Open vmuxPhone, then check Settings again.

Reinstall vmuxPhone

If the switch is still missing after a relaunch, the Live Activity extension may not have installed correctly. Delete vmuxPhone, reinstall from the App Store, sign in, and reconnect a session. The extension is bundled inside the main app — reinstalling restores it.

Check iOS version

Live Activities require iOS 16.2 or later. Open Settings → General → About and check the iOS version. If you are below 16.2, update iOS first.

Activity shows the wrong session

You have two activities and they look identical, or you tap one and the wrong session opens.

Add a unique host Label

The host name on the Live Activity card is the Label you gave the host inside vmuxPhone, falling back to user@host:port. Two hosts with the same user@host:port will produce identical-looking cards. Open the host inside vmuxPhone, set a distinctive Label, and the cards will diverge on the next update.

Disconnect everything and reconnect one at a time

If a tap consistently opens the wrong session — for example, you tap card A and session B opens — force-quit vmuxPhone, relaunch, and reconnect each session one at a time. The most likely cause is two activities sharing identifiers after a crash, which a fresh launch fixes.

Bell badge will not clear

The orange alert badge stays on even after you opened the session.

Fully view the session

The badge clears when vmuxPhone reports that you brought the matching session forward and viewed it for at least one update cycle. If you opened the app but immediately switched to another tab, the badge may not have cleared. Tap into the session, leave it visible for a couple of seconds, and the badge will go away on the next activity update.

Force-quit vmuxPhone

If the badge is persistent after a clean view, force-quit and relaunch. The activity will republish without the alert flag.

Related

• Enabling Live Activities — the switches.
• Dynamic Island — the cutout layouts.
• Lock Screen presentation — the banner.
• vmuxPhone troubleshooting — for the underlying connection issues that block activities from starting.
• vmuxPhone — Live Activities — the in-app rules.