Live Activities

What it is

vmuxPhone publishes an iOS Live Activity for every connected terminal session. The activity appears on the Lock Screen, in the Dynamic Island on iPhones that have one, and (on iOS 17 and later) in the StandBy display when the iPhone is charging horizontally. It tells you that a session is alive, where it is connected, and whether anything important has happened recently — without you needing to open the app.

The Live Activity is read-only: tapping it brings the matching session forward in vmuxPhone. There are no interactive buttons in the activity itself today.

Lifecycle

vmuxPhone starts a Live Activity automatically when a session connects. It updates the activity every time output arrives, the connection state changes, the bell rings, or the iOS lifecycle sends the app to the background. It ends the activity when the session disconnects or fails. You do not start or stop activities manually.

A few rules that govern when activities appear:

They start only on a successful connect. Pre-connect states like Connecting… and Mosh bootstrap… stay inside the app.
They update at most every 2 seconds while the session is active. Faster bursts of output are coalesced.
They end immediately on disconnect — there is no "session ended" lingering banner.
Multiple windows produce multiple activities. Each one references its own host.

What is shown

Three layouts exist. iOS picks one based on where the activity is rendered.

The full activity. The banner shows:

Host display name — the Label you gave the host, or user@host:port when no label is set.
Subtitle — the destination string (user@host:port).
Snippet — the active working directory if vmux's shell integration has reported one; otherwise the most recent terminal title.
Connection status — one of Connected, Background, Paused, Reconnecting…, Disconnected, or the failure reason.
Alert badge — a colored dot turns on when the bell has rung since you last brought the session forward.
Last update timestamp — relative time since the activity last refreshed.

Dynamic Island compact and minimal states

On iPhones with a Dynamic Island, the system collapses the activity into a small pill or a single dot at the edges of the cutout when other content needs space. vmuxPhone provides:

State	What it shows
Compact (leading)	A terminal symbol.
Compact (trailing)	The connection status indicator (a small dot whose color reflects the state).
Minimal	A single dot whose color matches the connection status.

When you long-press the Dynamic Island, iOS expands the activity into the full layout (same content as the Lock Screen banner).

Expanded Dynamic Island

The expanded form is what you see when you long-press a compact activity. The layout matches the Lock Screen banner, with the same host title, subtitle, snippet, status, and alert badge.

Status text mapping

The connection status field maps the session's internal lifecycle to a short label:

Internal state	Label
Connected (active)	Connected
Connecting	Connecting…
Disconnected	Disconnected
Failed (with reason)	Connection failed: reason
Background grace	Background
Suspended resumable	Paused
Reconnecting	Reconnecting…

These labels match the in-app status line you see at the top of the terminal, so you can rely on the activity for the same information.

Alert badge

Every time the remote shell rings the bell (\a byte) while vmuxPhone is in the background or the screen is locked, the alert badge turns on. The badge stays on until you bring the session forward, which clears it the next time the activity updates.

The bell also fires a one-shot iOS notification (see Notifications) and triggers a haptic. The activity badge is the persistent indicator — even after you dismiss the notification, the badge tells you that something happened.

Tap behavior

Tapping the Lock Screen banner or the Dynamic Island opens vmuxPhone with the matching session selected. If multiple windows are open, the workspace switches to the right one before unhiding the keyboard. Authentication for App Lock — Face ID — runs first if you have it on.

Enabling and disabling

Live Activities respect a system-level switch in Settings → Face ID & Passcode → Allow Access When Locked → Live Activities and a per-app switch in Settings → vmux → Live Activities. Both must be on.

vmuxPhone does not have its own toggle. If you turn the system switch off, vmuxPhone still tries to publish but iOS rejects the request and nothing appears. Turning the switch back on without restarting the app makes the next session connect publish a fresh activity.

There is currently no way to publish a Live Activity for a disconnected session, and there is no scheduled "reminder" activity.

Limitations

vmuxPhone does not yet receive push updates from the server, so the activity refreshes only while the app or its background runtime is alive. If iOS suspends the runtime fully, the activity freezes at its last state until the app foregrounds again.
Activities do not have interactive buttons today. A future release may add a one-tap reconnect or disconnect button via App Intents.
The activity is bound to the iOS device, not to your iCloud account. Other devices do not see your iPhone's Live Activities.

Troubleshooting

Live Activity does not appear

Verify the system switch in Settings → vmux → Live Activities is on. Confirm that Settings → Face ID & Passcode → Allow Access When Locked → Live Activities is also on. Disconnect and reconnect the session — the activity is created on connect.

Notifications — bell, command-completed, and disconnect alerts.
Mosh on iPhone — the lifecycle states the activity reflects.
Live Activity manual — full manual for the Live Activity surface across the family.