Boot a Virtual iPhone via Apple's Virtualization.framework

Using Apple's Virtualization.framework, one can boot a virtual iPhone through the PCC research VM infrastructure. A single command, vphone-cli vm create, initiates the entire process, which includes downloading, patching, DFU restore, CFW installation, and first boot. To update to a newer iOS version, specify an IPSW file using the --iphone-source and --cloudos-source flags.

The vphone-cli tool generates various patch variants, each with incremental security bypass capabilities. These can be selected using the --variant flag. All generated files are stored under the ~/.vphone directory, outside the repository and the .app, ensuring portability of the signed bundle.

The environment can be customized using $VPHONE_ROOT, $VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR, and $VPHONE_ROOT variables. By default, the ipsws/, tools/, and debs/ caches are located directly under the active root. To disable System Integrity Protection (SIP) and AMFI entirely, reboot into macOS and set the AMFI boot-arg after completely disabling SIP.

If SIP remains enabled, allowlisting the binary with amfidont is an option, though AMFI will be enabled system-wide. The tool may not work on hardware that is itself a VM, so a non-nested macOS 15+ host is required. System apps will not install during iOS setup, so avoid selecting regions with extra regulatory checks, such as Japan or the EU.

If encountering EXC_GUARD errors during iOS setup, re-patch the system with vphone-cli fw patch, specifying the variant and forcing an EXC_GUARD fix. Re-restore and reinstall after applying the patch. Always ensure the VM is set to always use iOS 18 base images.

For installing a .ipa/.tipa file, use the VM's Install menu, either via drag-and-drop or file picker. During CFW installation, ldid-procursus may hang when re-signing system binaries due to a bug in versions up to 2.1.5-procursus7. This issue arises from undefined behavior in bytes(uint64_t) calls that resolve to a 0-length loop counter. If this occurs, rebuild ldid-procursus from source and link it using Homebrew.