Run a virtual iPhone on an Apple Silicon Mac.
Troubleshooting
Find the symptom or error message you see, then follow the fix under it. For network problems, see Networking.
vphone-vm is killed before the VM opens
Run the host preflight:
vphone-cli host preflightThe CLI is unentitled, so it keeps running and can explain an AMFI refusal of its signed
vphone-vmcompanion.If you rebuilt the bundle, the cdhash changed. Allow the new binaries with the bundled helper as described in Host setup.
Virtualization is not available on this hardware
PV=3 guests cannot be nested. Boot on an Apple Silicon Mac, not inside another macOS VM.
vm create printed vphoned success, but no VM is running
That is expected. Creation starts a temporary GUI boot, sends a real ping, and stops that boot before returning. Start the VM for use:
vphone-cli vm launch <name>
Stuck at "Press home to continue"
Click the Home button in the VM window's title bar. The current JB workflow does not install a VNC server.
App exits with EXC_GUARD / GUARD_TYPE_MACH_PORT
The kernel patch kernel-boot-thread_guard_violation stops fatal Mach port guard delivery. It applies only on an iOS 18 base, where it is needed to boot, and every preset turns it on there. Other bases cannot select it, so an app that trips this guard on a 26.x base still exits. See issue #291.
Restore or first boot fails
- In a manual flow, keep the VM in DFU until
restoreexits. - Check that online ticket requests can reach Apple.
- For the complete pipeline, rerun
vm createwith a new name and-vfor tool detail. - Avoid creating VMs in parallel when memory or disk is tight.
- Before combining an iPhone IPSW with a PCC image, check Firmware compatibility.
The guest boots, but vphoned does not answer during creation
The first-boot check times out after 300 seconds. Creation uses a GUI boot because a newly restored guest may not bring up vphoned during its first headless boot. See Create and run for what the success marker proves.