Lock Screen presentation
How vmuxPhone Live Activities render on the Lock Screen, including layout, taps, and multi-session stacking.
What you see on the Lock Screen
Wake the iPhone without unlocking it and any vmuxPhone Live Activity appears as a card just below the clock. The card is the full Live Activity layout — same content as the expanded Dynamic Island, formatted for the wider Lock Screen. Glance at the iPhone, see the host, the status, and the latest snippet, then sleep the screen again. You never had to unlock.
The card is read-only. You cannot type into it, scroll the snippet, or trigger a reconnect. Tapping it opens vmuxPhone (after Face ID and App Lock authentication, if those are configured) and brings the matching session forward.
Layout regions
The Lock Screen card is divided into three logical regions, all on a single row except for the snippet which wraps below.
| Region | Content | Notes |
|---|---|---|
| Leading | Host display name in a heading font, with the connection status below it as caption text | Host name is the Label you set; falls back to user@host:port |
| Trailing | An orange bell glyph when the alert flag is on; nothing otherwise | The bell is the only colored element on the leading row |
| Snippet block (full width, below) | Up to three lines of monospaced terminal text on a translucent background | Hidden entirely when there is nothing to show |
The card uses iOS's standard Lock Screen background blur and material — the snippet block sits on a .ultraThinMaterial rounded rectangle so it stays legible against any wallpaper. There is no center region in the Lock Screen layout — the host and status sit on the leading edge, the bell sits on the trailing edge, and the snippet flows below them.
Host name
The first line is the host name in a heading font, truncated to one line. This is the Label you gave the host inside vmuxPhone, or user@host:port if you have not set a Label. If you frequently confuse one host with another, edit the host inside vmuxPhone and add a distinctive Label — that is the easiest way to tell two activities apart on the Lock Screen.
Status caption
Directly under the host name, in caption text, is the connection status. The labels match the in-app status line:
| State | Caption |
|---|---|
| Connected (active) | Connected |
| Reconnecting | Reconnecting… |
| Background grace | Background |
| Suspended resumable | Paused |
| Disconnected (clean) | Disconnected |
| Failed | Connection failed: reason |
Watching the caption is the cheapest way to tell whether your session is healthy. If it stays at Connected while you are walking around, your network handover is working. If it flips to Reconnecting… for a moment and then back, that is a normal cellular handoff. If it stays at Reconnecting… for more than 30 seconds, see troubleshooting.
Alert badge
When the remote shell rings the bell while vmuxPhone is in the background, the activity flips on its alert flag. The Lock Screen renders this as an orange bell glyph on the trailing edge of the card. The bell stays on until you bring the session forward — opening vmuxPhone, focusing the matching pane, and viewing it for at least one update cycle clears the badge.
The bell on the Lock Screen card is the persistent reminder. The same event also fires a one-shot iOS notification (see Notifications on iPhone) and a haptic, but those are dismissable. The activity badge is what tells you "this happened" tomorrow morning when you wake up and look at the Lock Screen.
Snippet block
Below the host row sits the snippet — up to three lines of monospaced text on a translucent rounded background. The snippet is sourced from one of two places, in order:
- The current working directory, if vmux's shell integration has reported one
- The most recent terminal title
When neither is available — for instance, immediately after connect, before any output has arrived — the snippet block is hidden entirely and the card collapses to just the host row. The block reappears the moment the first meaningful update lands.
The snippet is visual only. It is not selectable text and you cannot copy from it.
Tap behavior
Tapping the Lock Screen card unlocks the iPhone (if you have Face ID configured, the gaze authentication runs first), then launches vmuxPhone. vmuxPhone selects the workspace tab matching the activity's session, scrolls the terminal to the bottom, and brings up the keyboard if the session is connected.
If you have App Lock enabled inside vmuxPhone, the App Lock biometric prompt also runs before the session becomes visible. This is in addition to the iOS unlock. Cancel either prompt and the app stays at the App Lock screen until you authenticate.
If the matching session has been disconnected since the activity was published, vmuxPhone opens to the workspace and shows the workspace panel rather than the terminal. From there you can reconnect.
Multi-session stacking
iOS stacks multiple Live Activities on the Lock Screen automatically. If vmuxPhone has three connected sessions, you see three vmux cards — one per session — sorted by recency. There is no special vmux logic involved; iOS handles the layout.
| Behavior | Notes |
|---|---|
| Stack order | Most recently updated activity on top |
| Maximum visible | iOS shows up to two activities by default, with the rest behind a "show more" affordance |
| Collapse / expand | Pull down on the Lock Screen to see all activities |
| Per-card tap | Each card opens its own session in vmuxPhone |
If two of your hosts have similar names, the cards can look identical at a glance. Edit one host inside vmuxPhone and give it a distinctive Label — the host name is what differentiates the cards, and a unique label is the only way to make that visible.
Always-on display and StandBy
On iPhones with an always-on display (iPhone 14 Pro and later), the Lock Screen card stays visible at reduced brightness when the phone is sleeping face-up. On iOS 17 and later, the activity also appears in StandBy when the iPhone is charging horizontally — the same card content, in a layout iOS picks for ambient viewing.
You do not configure either of these. They use the same Live Activity that the Lock Screen does.
Privacy on the Lock Screen
The card is visible to anyone who can see your Lock Screen, even without unlocking. The visible content is:
- The host Label or
user@host:port - The current working directory or terminal title (the snippet)
- Whether the bell rang
If a session is connected to a sensitive host or a sensitive directory, that detail is on the Lock Screen until the session disconnects. Use the system switch under Settings → Face ID & Passcode → Allow Access When Locked → Live Activities to suppress all Live Activities on the Lock Screen while keeping the Dynamic Island layout intact.
Related
- Dynamic Island — the same content, formatted for the cutout.
- Enabling Live Activities — system and per-app switches.
- Troubleshooting — when the card does not appear.
- vmuxPhone — Notifications — the bell event also fires a notification.
- vmuxPhone — Live Activities — the in-app rules.