Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Keep the Lock Screen lit while Auto-Lock is Never

Jacky44032381d227
diff --git a/Research/Guest/lock_screen_idle_timer.md b/Research/Guest/lock_screen_idle_timer.md
new file mode 100644
index 00000000..2bc0b11a
--- /dev/null
+++ b/Research/Guest/lock_screen_idle_timer.md
@@ -0,0 +1,138 @@
+# Auto-Lock "Never" and the Lock Screen
+
+A guest with Settings › Display & Brightness › Auto-Lock set to Never still
+went dark by itself. vphoned's `GuestLockScreenIdle`
+(`VPhoneDaemon/Daemon/GuestLockScreenIdle.swift`) and its `display.auto_lock`
+method rest on the measurements below, taken on 2026-10-03 against
+`nettest-01` (iOS 27.0, 24A435) and `locktest-ipad` (iPadOS 26.6.2, 23G90)
+over `vphone.sock` with `settings.get/set/delete`, `system.respring`,
+`device.snapshot` (`lock.locked`, `lock.screen_off`) and `logs.syslog`
+filtered to SpringBoard's `IdleTimer` category.
+
+## What goes dark
+
+The setting was in effect. On `ipad-mini-01`, `ipad-pro-13` (iPadOS 26.6.2)
+and `nettest-01`,
+`/var/mobile/Library/UserConfigurationProfiles/EffectiveUserSettings.plist`
+held `restrictedValue.maxInactivity.value = 2147483647`, and SpringBoard logged,
+for the Home Screen and for a foreground app:
+
+```
+dsc … <mode: Auto; …> reason:MCFeatureAutoLockTime (2.14748e+09) is gt MAX (3600)
+-> dsc … <mode: Disabled; …> reason:after setup, shouldWarn is NO and expireInterval is <never>
+```
+
+An unlocked guest left alone stayed lit: 21 minutes on `ipad-mini-01`, 9 on
+`nettest-01`, with no backlight or lock line in SpringBoard or backboardd.
+
+The Lock Screen is the part that does not follow the setting.
+`SBDashBoardIdleTimerProvider` asks for `duration: Default`, and the same
+factory answers six seconds whatever Auto-Lock says:
+
+```
+idleTimerDescriptorForBehavior: <SBIdleTimerBehavior: …; duration: Default; mode: Inherit; warnMode: Inherit>
+dsc … reason:MCFeatureAutoLockTime (2.14748e+09) is gt MAX (3600)
+dsc … <…; total: 6.0s> reason:duration is Default
+applying updated idle timer descriptor: <SBIdleTimerDescriptor: …; mode: Inherit; …; total: 6.0s> reason:SBDashBoardScreenOff
+```
+
+Waking a guest to the Lock Screen and leaving it, `lock.screen_off` turned
+true 8 seconds later on `nettest-01` and 7 on `locktest-ipad`. A guest lands
+on the Lock Screen after every boot, every SpringBoard restart
+(`system.respring`, `setup.skip`, a crash) and every press of the side button,
+and nobody is holding it. So it boots, shows the Lock Screen and is black a
+few seconds later, which reads as the device going to standby on its own.
+
+Nothing on the host does this. `vphone-vm` sends the power key only from the
+Device menu, the Controls panel and the automation socket's `key` request.
+
+## `SBMinimumLockscreenIdleTime`
+
+SpringBoard reads `SBMinimumLockscreenIdleTime` from `com.apple.springboard`
+(user mobile) and, when it is set, uses it in place of the six seconds:
+
+```
+dsc … <…; total: 6.0s> reason:duration is Default
+dsc … <…; total: 2147483647.0s> reason:totalInterval (6) is gte 0
+applying updated idle timer descriptor: <…; mode: Inherit; …; total: 2147483647.0s> reason:SBDashBoardScreenOff
+```
+
+Each row sets the key, then wakes the guest to the Lock Screen and reads the
+descriptor SpringBoard applies.
+
+| Change | Lock Screen timeout |
+| --- | --- |
+| key absent | 6 s |
+| 600, then SpringBoard restarted | 600 s; lit after 40 s |
+| 7200, then SpringBoard restarted | 7200 s |
+| 2147483647, then SpringBoard restarted | 2147483647 s |
+| the same value written again, no restart | unchanged |
+| set while absent, no restart (integer or float) | 6 s |
+| a different value while set, no restart | 6 s, until SpringBoard restarts |
+| removed, no restart | 6 s |
+
+The table is `nettest-01`. On `locktest-ipad` the absent, 2147483647 and
+removed rows gave the same results (6 s and off after 7; lit after 45 s; off
+after 7).
+
+SpringBoard takes the value when it starts. A later change is not picked up,
+and a change of an existing value drops the override for the rest of that
+SpringBoard's life. Writing the value it already has is harmless.
+
+The unlocked timeout is not affected: with the key at 2147483647 and
+Auto-Lock at 30 seconds, the Home Screen went dark after 32 seconds.
+
+## What vphoned does
+
+`GuestLockScreenIdle` mirrors Auto-Lock into that key:
+
+- Auto-Lock is Never and the key is not 2147483647: write 2147483647.
+- Auto-Lock is anything else and the key is 2147483647: remove it. Any other
+ value is someone else's and stays.
+
+It runs first thing when vphoned starts, before the rest of startup, and again
+on `com.apple.managedconfiguration.effectivesettingschanged`, the Darwin
+notification profiled posts after rewriting `EffectiveUserSettings.plist`.
+
+Settings does not commit Auto-Lock when a row is tapped. The file kept the old
+value for 75 seconds with the new row checked, and changed within two seconds
+of leaving Settings; vphoned's log line followed in the same two seconds.
+
+Because SpringBoard reads the key once:
+
+- A guest whose key is already in place boots to a Lock Screen that stays lit.
+- Turning Never on in Settings writes the key once Settings commits, and it
+ holds from the next SpringBoard start (reboot or `system.respring`).
+- Turning Never off removes the key, and the Lock Screen is back to six
+ seconds immediately.
+
+Measured with the vphoned of this change, on both guests:
+
+| Step | Result |
+| --- | --- |
+| Auto-Lock Never, key absent, guest started; the host replaces vphoned over HTTP about six seconds after boot | key written at startup; the Lock Screen of that same boot uses 2147483647 s and is lit after 40 s |
+| Auto-Lock to 2 minutes (`locktest-ipad`) | key removed; Lock Screen off after 7 s |
+| Auto-Lock back to Never, then `system.respring` (`locktest-ipad`) | key written; Lock Screen lit after 60 s |
+
+The first row means vphoned's write beats SpringBoard's read on a normal boot
+even when vphoned is first replaced by the host. That is an observation on
+these two guests, not a guarantee.
+
+`display.auto_lock` reports `{auto_lock_seconds, never,
+lock_screen_minimum_seconds}`; capability `display_auto_lock`.
+
+The side button still turns the screen off; that is a request, not a timeout.
+
+## Reproducing
+
+```sh
+vphone-launchpad-cli guest rpc <vm> display.auto_lock
+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # screen off
+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # Lock Screen
+# after 10 s and again after a minute:
+vphone-launchpad-cli guest rpc <vm> device.snapshot # lock.screen_off
+vphone-launchpad-cli guest rpc <vm> logs.syslog '{"seconds":6,"process":"SpringBoard","max_lines":5000}'
+```
+
+The `IdleTimer` line `applying updated idle timer descriptor` carries the
+`total` SpringBoard uses.
diff --git a/Research/README.md b/Research/README.md
index 860b6ff3..8e898813 100644
--- a/Research/README.md
+++ b/Research/README.md
@@ -20,7 +20,7 @@ This directory keeps the evidence behind firmware patches, restore and the self-
| Other patches and captures | [Launchd jetsam](Patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](Patches/hv_vmm_present_usermode_xrefs.md), [reference capture](Patches/patch_reference_capture.md) |
| Restore | [DFU probe](Restore/virtual_dfu_probe.md), [in-process restore](Restore/native_restore_architecture.md) |
| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/runtime_dependency_tiers.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md) |
-| Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md), [RootHide bootstrap base](Guest/roothide_bootstrap_base.md), [the Mac's .local name](Guest/mac_name_resolution.md) |
+| Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md), [Auto-Lock on the Lock Screen](Guest/lock_screen_idle_timer.md), [RootHide bootstrap base](Guest/roothide_bootstrap_base.md), [the Mac's .local name](Guest/mac_name_resolution.md) |
| Historical project records | [Migration ledger](History/intg_update_status.md), [manifest refactoring summary](History/manifest_and_refactoring_summary.md) |
`KernelSymbols/` holds symbol datasets and indexes; `Reference/` holds source references when present. They are evidence inputs, not steps for running the distributed app. The files in `History/` are preserved snapshots and may describe scripts or variants that have since been removed.
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index b7f06c1d..e1f529d7 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -270,7 +270,7 @@ request carries `"force": true`.
| Area | Methods |
| --- | --- |
| Device | `device.snapshot`, `device.info` (snapshot plus network, screen, rotation, brightness, volume, low power, Developer Mode, agent), `device.screen`, `device.network`, `device.ioreg {plane}`, `device.environment`, `device.basebin {archive?}` |
-| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `audio.volume {value?, category?}`, `audio.state` |
+| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`: Auto-Lock and the Lock Screen timeout vphoned keeps in step with it, see below; capability `display_auto_lock`), `audio.volume {value?, category?}`, `audio.state` |
| Input | `input.touch`, `input.hid`, `input.button {name}`, `input.key {name}`, `input.type {text, delay_ms?}`, `input.paste {text}`, `input.tap`, `input.double_tap`, `input.long_press`, `input.swipe`, `input.drag {points}`, `input.touch_sequence {events}` — gesture coordinates are screen points |
| UI | `ui.tree` (alias `accessibility.tree`), `ui.element_at`, `ui.tap_element`, `ui.wait`, `ui.wait_gone`, `ui.ocr {languages?, min_confidence?}`, `ui.describe`, `screen.screenshot` |
| Processes | `processes.list {filter?}`, `processes.kill {pid, signal?}` **force**, `memory.jetsam`, `memory.pressure` (only the three kernel memory sysctls, for polling) |
@@ -289,6 +289,16 @@ request carries `"force": true`.
| Profile UDID | `udid.get`, `udid.set {udid}`, `udid.clear` — each returns `{udid, path}`, the UDID the guest gives its profile checks and the host (null: the guest's own) and the settings file it came from; `set` and `clear` also return `restarted_pids`, `usb_serial` and `usb_reenumerated` (see below) |
| Setup Assistant | `setup.status` (`{pending, running, pid, setup_done, setup_version, current_version}`), `setup.skip` **force** (sets `SetupDone`, `SetupFinishedAllSteps` and `SetupVersion` in `com.apple.purplebuddy`, restarts SpringBoard, returns the status plus `respring`); `/v1/health` carries `setup_pending` — see `Research/Guest/setup_assistant_skip.md` |
+`display.auto_lock` reads Settings' Auto-Lock (`maxInactivity` in profiled's
+`EffectiveUserSettings.plist`) and SpringBoard's `SBMinimumLockscreenIdleTime`.
+SpringBoard honors Auto-Lock only while unlocked; on the Lock Screen it turns
+the screen off after six seconds unless that key says otherwise. vphoned keeps
+the key at "never" while Auto-Lock is Never and removes it when Auto-Lock is
+anything else (`VPhoneDaemon/Daemon/GuestLockScreenIdle.swift`), at startup
+and whenever the settings change. SpringBoard reads the key when it starts, so
+a newly written one holds from the next boot or respring. Measurements:
+`Research/Guest/lock_screen_idle_timer.md`.
+
`network.static_names.set` replaces the names the guest resolves locally, given
as `entries: [{address, names}]` (IPv4 only; an empty list withdraws them).
vphoned registers each name as a LocalOnly, known-unique A record with the
@@ -312,7 +322,7 @@ Account passwords, boot logo rendering and package installation, removal and
repository changes are deliberately not exposed. `/v1/health` lists the new
areas in `capabilities` (`device_info`, `display`, `audio`, `input_gestures`,
`ui_inspection`, `processes`, `services`, `logs`, `network_capture`,
-`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_static_names`, `network_resolve`) so a host can hide
+`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_static_names`, `network_resolve`, `display_auto_lock`) so a host can hide
panels an older agent cannot serve. icli failures reach the caller with
icli's own error `code` (`failed`, `unavailable`, `device_locked`, …) and
message.
diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.md
index d73885af..1673ce99 100644
--- a/Skills/vphone-guest-control/references/rpc-methods.md
+++ b/Skills/vphone-guest-control/references/rpc-methods.md
@@ -52,6 +52,7 @@ invalid-request error, read the source named there instead of guessing keys.
| `screen.screenshot` | none | Base64 JPEG with `mime_type`, `width`, `height` (1290×2796) |
| `display.brightness`, `audio.volume` | `value?` | Omit `value` to read |
| `display.rotation`, `display.orientation` | `orientation?` | |
+| `display.auto_lock` | none | Auto-Lock in seconds (`never` when it is Never) and the Lock Screen timeout vphoned sets to match |
| `device.ioreg` | `plane` | e.g. `IODeviceTree` |
## Input
diff --git a/VPhoneDaemon/Daemon/GuestAPI+Device.swift b/VPhoneDaemon/Daemon/GuestAPI+Device.swift
index 6ae70e6d..572e0382 100644
--- a/VPhoneDaemon/Daemon/GuestAPI+Device.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI+Device.swift
@@ -60,6 +60,8 @@ extension GuestAPI {
throw GuestAPIError.invalidRequest("locked must be true or false")
}
return try setRotationLock(locked)
+ case "display.auto_lock":
+ return GuestLockScreenIdle.describe()
case "audio.volume":
let category = optionalString(params, "category") ?? "Audio/Video"
if params["value"] != nil {
diff --git a/VPhoneDaemon/Daemon/GuestAPI.swift b/VPhoneDaemon/Daemon/GuestAPI.swift
index 2def68eb..22399e74 100644
--- a/VPhoneDaemon/Daemon/GuestAPI.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI.swift
@@ -82,6 +82,7 @@ enum GuestAPI {
"device_info",
"display",
"display_orientation",
+ "display_auto_lock",
"audio",
"input_gestures",
"ui_inspection",
diff --git a/VPhoneDaemon/Daemon/GuestLockScreenIdle.swift b/VPhoneDaemon/Daemon/GuestLockScreenIdle.swift
new file mode 100644
index 00000000..05cb81d9
--- /dev/null
+++ b/VPhoneDaemon/Daemon/GuestLockScreenIdle.swift
@@ -0,0 +1,94 @@
+import Foundation
+import IcliKit
+import notify
+
+/// Makes Auto-Lock "Never" hold on the Lock Screen too.
+///
+/// Settings › Display & Brightness › Auto-Lock sets `maxInactivity`, and
+/// SpringBoard applies it only while the device is unlocked. On the Lock
+/// Screen it uses its own six seconds whatever the setting says, so a guest
+/// that has just booted, or whose SpringBoard has just restarted, goes dark
+/// before anyone looks at it.
+///
+/// SpringBoard reads one more value there, `SBMinimumLockscreenIdleTime` in
+/// `com.apple.springboard`, and replaces the six seconds with it. vphoned
+/// keeps that key at the same "never" while Auto-Lock is Never, and removes
+/// it again when Auto-Lock is anything else. A value some other tool put
+/// there is left alone.
+///
+/// SpringBoard takes the key when it starts. Setting it later does nothing
+/// until SpringBoard restarts, and changing or removing it puts the six
+/// seconds back at once. So this runs before anything else at startup, to be
+/// ahead of SpringBoard on a boot where the key is missing.
+///
+/// Measured on iOS 27.0 and iPadOS 26.6.2; see
+/// Research/Guest/lock_screen_idle_timer.md.
+enum GuestLockScreenIdle {
+ /// profiled's merged settings for user mobile. It rewrites the file and
+ /// then posts `changedNotification`; ManagedConfiguration's own clients
+ /// re-read it on the same signal.
+ private static let settingsPath = "/var/mobile/Library/UserConfigurationProfiles/EffectiveUserSettings.plist"
+ private static let changedNotification = "com.apple.managedconfiguration.effectivesettingschanged"
+ private static let domain = "com.apple.springboard"
+ private static let key = "SBMinimumLockscreenIdleTime"
+ /// What Settings stores for "Never", in seconds.
+ private static let never = Int(Int32.max)
+ private static let queue = DispatchQueue(label: "vphoned.lock-screen-idle", qos: .utility)
+
+ static func startOnStartup() {
+ queue.sync { apply(reason: "startup") }
+ var token: Int32 = 0
+ let status = notify_register_dispatch(changedNotification, &token, queue) { _ in
+ apply(reason: "settings changed")
+ }
+ if status != 0 {
+ NSLog("vphoned: lock screen idle: cannot observe Auto-Lock changes (notify status %u)", status)
+ }
+ }
+
+ /// Auto-Lock in seconds, `never` for Never, nil when profiled has not
+ /// written its settings yet.
+ static func autoLockSeconds() -> Int? {
+ guard let data = FileManager.default.contents(atPath: settingsPath),
+ let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
+ let values = plist["restrictedValue"] as? [String: Any],
+ let setting = values["maxInactivity"] as? [String: Any]
+ else { return nil }
+ return (setting["value"] as? NSNumber)?.intValue
+ }
+
+ static func lockScreenMinimum() -> Int? {
+ let value = CFPreferencesCopyValue(key as CFString, domain as CFString, "mobile" as CFString, kCFPreferencesAnyHost)
+ return (value as? NSNumber)?.intValue
+ }
+
+ static func describe() -> [String: Any] {
+ let autoLock = autoLockSeconds()
+ let minimum = lockScreenMinimum()
+ return [
+ "auto_lock_seconds": autoLock.map { $0 as Any } ?? NSNull(),
+ "never": autoLock.map { $0 >= never } ?? false,
+ "lock_screen_minimum_seconds": minimum.map { $0 as Any } ?? NSNull(),
+ ]
+ }
+
+ private static func apply(reason: String) {
+ guard let autoLock = autoLockSeconds() else {
+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is not readable, nothing changed", reason)
+ return
+ }
+ let minimum = lockScreenMinimum()
+ do {
+ if autoLock >= never {
+ guard minimum != never else { return }
+ _ = try writePreference(domain: domain, key: key, value: .int(Int64(never)))
+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is Never, Lock Screen follows from the next SpringBoard start", reason)
+ } else if minimum == never {
+ _ = try deletePreference(domain: domain, key: key)
+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is %d s, Lock Screen is back to its own timeout", reason, autoLock)
+ }
+ } catch {
+ NSLog("vphoned: lock screen idle (%@): %@", reason, String(describing: error))
+ }
+ }
+}
diff --git a/VPhoneDaemon/Daemon/main.swift b/VPhoneDaemon/Daemon/main.swift
index db98c05a..c5002df5 100644
--- a/VPhoneDaemon/Daemon/main.swift
+++ b/VPhoneDaemon/Daemon/main.swift
@@ -13,6 +13,8 @@ if mode != 1 {
}
guard vp_native_watch_proxy() == 0 else { exit(1) }
+// First, so the Lock Screen timeout is in place before SpringBoard reads it.
+GuestLockScreenIdle.startOnStartup()
vp_vcam_start()
// Multi-finger injection is resolved here so the first pinch is not the call
// that pays for `dlopen`; a base without the symbols logs and stays a no-op.