vmux Live Activity
ActivityKit-based Dynamic Island and Lock Screen indicator for active vmuxPhone terminal sessions.
What it is
vmux Live Activity is the iOS surface that puts your active vmuxPhone session on the Lock Screen, in the Dynamic Island, and (on iPhones that support it) in StandBy. It is a separate app extension that ships inside vmuxPhone — you do not install it on its own. Whenever vmuxPhone has a connected terminal session, the Live Activity is the small piece of system UI that tells you the session is alive, where it is connected, and whether anything has happened since you last looked at it.
It is read-only. There are no buttons in the activity. Tapping it brings the matching session forward in vmuxPhone after App Lock authentication, if you have it on.
This page is the overview for the Live Activity surface. Sibling pages cover enabling, the Dynamic Island layouts, the Lock Screen presentation, and troubleshooting.
What it shows
Every Live Activity carries the same four fields, regardless of where iOS chooses to render it:
- Host name. The Label you gave the host in vmuxPhone, or
user@host:portif no Label is set. This is the identity of the session. - Connection status. A short label that mirrors the in-app status line — for example Connected, Reconnecting…, Background, Paused, Disconnected, or a failure reason.
- Snippet. The most recent meaningful line from the terminal — typically the working directory reported by shell integration, or the latest terminal title if not. Up to three lines of monospaced text.
- Alert badge. A bell or a colored dot that turns on when the remote shell rang the bell while you were not looking. Stays on until you bring the session forward.
The fields are sourced from a small content state that vmuxPhone updates each time output arrives, the connection state changes, the bell rings, or the app moves between foreground and background.
Where it shows up
iOS picks one of three layouts depending on context.
| Surface | Layout | When it appears |
|---|---|---|
| Lock Screen | Full banner with host, status, snippet, and alert bell | When the iPhone is locked or in Notification Center |
| Dynamic Island (compact / minimal) | A terminal symbol on one side and a status dot on the other, or a single dot when crowded | While vmuxPhone is in the background and another app is in front |
| Dynamic Island (expanded) | The same content as the Lock Screen banner | While you long-press a compact activity |
The compact and minimal Dynamic Island states drop the snippet and the host name to fit in the space around the front camera cutout. Long-press to expand and you get everything back.
What the icons mean
| Element | Meaning |
|---|---|
| Terminal glyph (compact / minimal) | The activity belongs to a vmuxPhone session |
| Terminal glyph in orange | The bell rang since you last viewed the session |
| Status dot in green | Session is Connected |
| Status dot in orange | Session has an active alert that has not yet been viewed |
| Status dot in gray | Session is in any other state — connecting, reconnecting, paused, background, or disconnected |
| Bell glyph (Lock Screen) | The bell badge — same meaning as the orange dot |
The dot color is intentionally coarse. The exact state lives in the connection status text. The dot is for at-a-glance scanning.
Activity state reference
The connection status field is the most important thing the activity carries. It maps directly from vmuxPhone's session lifecycle:
| Internal state | Status label shown |
|---|---|
| Connected (active) | Connected |
| Connecting | Connecting… |
| Disconnected (clean) | Disconnected |
| Failed | Connection failed: reason |
| Background grace | Background |
| Suspended resumable | Paused |
| Reconnecting | Reconnecting… |
These match the same labels you see at the top of the terminal in vmuxPhone, so the activity does not introduce new vocabulary.
System requirements
| Requirement | Minimum |
|---|---|
| iOS | iOS 16.2 or later |
| Dynamic Island | iPhone 14 Pro, 14 Pro Max, or any iPhone 15 / 16 / 17 model |
| Lock Screen card | All iPhones that meet the iOS 16.2 minimum |
| StandBy mode | iOS 17 or later, iPhone with always-on display recommended |
| Apps | vmuxPhone installed and signed in |
| System switch | Settings → Face ID & Passcode → Allow Access When Locked → Live Activities must be on |
| Per-app switch | Settings → vmux → Live Activities must be on |
If your iPhone does not have a Dynamic Island (older models, all iPhone SE), you still get the Lock Screen card and the StandBy view. The compact and minimal Dynamic Island layouts simply do not render — iOS has nowhere to put them.
Where to go next
- Enabling Live Activities — system switch, per-app switch, and how vmuxPhone decides when to start one.
- Dynamic Island — the compact, minimal, and expanded Dynamic Island states in detail.
- Lock Screen presentation — banner layout, taps, and stacking.
- Troubleshooting — for when something does not appear.
See also
- vmuxPhone — Live Activities — the in-app perspective on the same surface, including the lifecycle rules.
- vmuxPhone — the parent app whose sessions drive the activity.
- Widgets — Home Screen and StandBy widgets, which are a different surface.