khanhduytran0/LiveSimBooter

LiveSimBooter

An experimental native iPhone host for an arm64 iOS Simulator runtime. The native app owns UIKit, process launches, and display/input services; simulator programs run in separate LiveProcess instances using the device’s kernel. It does not emulate a CPU or boot a separate kernel. See the architecture for the process boundaries.

Setup

Start with the agent-assisted setup guide and AGENTS.md. The supported guest baseline is iOS Simulator 26.0, build 23A343. Runtime patches and private interfaces are pinned to that build; a different iOS 26.x or iOS 27 runtime is not an interchangeable input.

There is no in-app runtime installer. Supply the original runtime, signing identity, matching provisioning profiles, and device access, then use the tracked setup/build/sign/copy steps. Generated binaries and runtime files stay outside Git. Device migration covers transfer, App Group discovery, and rollback.

Running

After setup, open the app and tap Start on the IOSurface tab. Keep the native host in the foreground for baseline use. The persistent IOSurface, Fish, and Settings tabs share one simulator session; switching tabs does not restart guests. Fish belongs to simulator launchd, and Settings provides the guest performance HUD and touch-marker controls. The device picker changes the simulated model and resolution, then restarts the guest session. Silent background audio is optional and disabled by default.

Explicit guest arguments, such as --launchd-services or /bin/df, retain automatic startup for development tests. Guest launchctl can manage individual jobs and request a simulator userspace reboot; see guest control. The default guest handoff retains the native shared cache and redirects workqueue entry through a hardware breakpoint. Native-cache detachment remains a diagnostic mode, not the normal setup.

Status and limits

The matching runtime has reached SpringBoard with app icons on iPhone18,2 running iOS 27.0 build 24A435. Device tests have verified Contacts, touch and keyboard input, native Metal presentation, interactive Fish, and display settings. App launching also passed a cold-start check and two consecutive userspace reboots; these results do not establish complete app compatibility.

Home Screen → Edit → Edit Wallpaper supports color/gradient rendering. PosterBoard’s lock-screen path and direct activation remain broken with black output; the editor’s clipped Done button is also deferred. See wallpaper status.

Generic fork/execve, native PTYs, stopped/continued wait events, and full job control are not implemented. The supported process-replacement path uses POSIX_SPAWN_SETEXEC. Missing daemons, resources, and private API differences still limit applications; the observed Spotlight last-character crash is deferred. This remains a partial simulator environment.

Documentation

• Architecture and runtime handoff: loading, callbacks, threads, and debugger metadata.
• Processes, launchd, and SpringBoard services: lifecycle and compatibility.
• Framebuffer, IOSurface, and Metal: graphics transport and native helpers.
• Fish terminal, display settings, and guest control: interactive use.
• Shared cache, iOS binary compatibility, and debugging: preparation and evidence.

The documentation index includes the remaining topics and historical experiments. Use the setup guide for current commands; older notes describe earlier cache layouts and device configurations.

Development checks

On an Apple Silicon Mac with Xcode:

sh Tests/run.sh
python3 Tests/audit-local-runtime.py

Build the native host and guest shim separately using the setup guide. Local tests do not establish device signature acceptance, working mappings, or a successful UI operation.

License

Original project code is available under the MIT License, copyright 2026 Duy Tran. Apple-derived portions retain the Apple Public Source License 2.0, their notices, and separate obligations. See source licensing for the covered files, upstream source, and distribution/source-availability explanation. These licenses do not grant rights to separately supplied Apple runtime binaries or SDKs.