Boot a Virtual iPhone via Apple’s Virtualization.framework
Boot a virtual iPhone via Apple’s Virtualization.framework using PCC research VM infrastructure.
One command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):
vphone-cli vm create runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.
Update to a newer iOS by pointing fw prepare at an IPSW: —iphone-source /path/to.ipsw —cloudos-source /path/to.ipsw.
Five patch variants with increasing security bypass — pass one to —variant:
See research/0_binary_patch_comparison.md for the per-component breakdown.
Everything vphone-cli creates lives under ~/.vphone/ — kept outside the repo and the .app so the signed bundle stays portable. Redirect the whole tree with VPHONE_ROOT:
Precedence: the per-item overrides (VPHONE_LIBRARY_ROOT, VPHONE_VENV_DIR) win over VPHONE_ROOT, which wins over the ~/.vphone default. The ipsws/, tools/, and debs/ caches always sit directly under whichever root is active.
Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).
In Recovery (long-press power → Terminal):
Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):
Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont (leaves AMFI enabled system-wide).
Then reboot into macOS and:
zsh: killed ./vphone-cli — AMFI/debug restrictions aren’t bypassed; see Prerequisites (amfi_get_out_of_my_way=1 or amfidont).
Virtualization is not available on this hardware — your Mac is itself a VM; PV=3 guest boot can’t nest. Use a non-nested macOS 15+ host.
Stuck on “Press home to continue” — connect via VNC and right-click (two-finger click) to simulate the home button.
System apps won’t install — during iOS setup, don’t pick Japan or the EU as your region (extra regulatory checks the VM can’t satisfy); pick e.g. United States.
App crashes on launch with EXC_GUARD / GUARD_TYPE_MACH_PORT — re-patch with vphone-cli fw patch
Install a .ipa/.tipa — use the running VM’s Install menu (drag-drop or file picker).
cfw install hangs re-signing a system binary (e.g. Campo), memory climbing unbounded — known bug in ldid-procursus up to 2.1.5-procursus7 (the current Homebrew stable): bytes(uint64_t) calls __builtin_clzll(0) with no zero-guard, which is undefined behavior, and on this build resolves to a 0-length that underflows an unsigned loop counter — ldid spins writing one byte at a time into a growing buffer instead of terminating. Triggered by any entitlements plist containing an integer value of exactly 0 (some real Apple system binaries have these). Fixed upstream but not yet in a tagged release; rebuild from source: brew install —HEAD ldid-procursus && brew link —overwrite ldid-procursus. Kill the hung ldid process first (sudo kill -9
vphone-cli exposes a host control socket (