Vphone-cli Boots a Virtual Iphone on Mac Via Apple's Virtualization.framework

A single command, vphone-cli vm create, runs the entire pipeline — download, patch, DFU restore, CFW install, and first boot — while individual steps can be run manually or re-run one stage at a time. Users can update to a newer iOS by pointing fw prepare at an IPSW file with the --iphone-source and --cloudos-source flags. Five patch variants offer increasing security bypass levels, selected via the --variant flag; a per-component breakdown is in research/0_binary_patch_comparison.md.

All files created by vphone-cli live under ~/.vphone/, outside the repo and the.app bundle to keep the signed bundle portable. The whole tree can be redirected with $VPHONE_ROOT, with per-item overrides ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) taking precedence. The ipsws/, tools/, and debs/ caches always sit directly under the active root.

Two options exist for bypassing macOS security: Option A fully disables SIP and then disables AMFI via a boot-arg (most permissive). Option B keeps SIP on with debug-only relaxation and allowlists the binary with amfidont, leaving AMFI enabled system-wide. Known issues include: a "killed" error when AMFI/debug restrictions aren't bypassed; Virtualization unavailable on Macs that are themselves VMs (PV=3 guest boot can't nest); a "Press home to continue" hang solved by right-clicking in VNC; system apps failing to install if the region is set to Japan or the EU; and app crashes with EXC_GUARD / GUARD_TYPE_MACH_PORT, fixed by re-patching with --force-exc-guard.

A known bug in ldid-procursus up to 2.1.5-procursus7 causes cfw install to hang when re-signing a system binary, due to undefined behavior in bytes(uint64_t) calling __builtin_clzll(0). The fix is to rebuild from source with brew install --HEAD ldid-procursus and brew link --overwrite ldid-procursus, after killing the hung process. vphone-cli also exposes a host control socket (/vphone.sock) for programmatic control — screenshots, touch, swipes, hardware keys, clipboard — with each action returning an inline screenshot for AI-driven E2E testing. An MCP server wrapper, vphone-mcp, is available.