Running a Full iOS Virtual Machine on Apple Silicon: Inside vphone-cli
Hook
A Swift CLI tool with nearly 5,000 GitHub stars has no description, minimal documentation, and requires you to cripple your Mac’s security. Yet it accomplishes something Apple explicitly doesn’t support: running a full iOS virtual machine with kernel access on Apple Silicon.
Context
Apple’s Xcode Simulator has always been just that—a simulator. It runs iOS frameworks on macOS, not actual iOS. For security researchers, jailbreak developers, and anyone needing to inspect iOS at the kernel level, this means buying physical hardware and dealing with limited tooling. Meanwhile, Apple’s Private Cloud Compute research revealed they’ve been running iOS VMs internally using undocumented Virtualization.framework APIs.
vphone-cli reverse-engineers this PCC infrastructure to boot what the project calls ‘iOS 26’ as a virtualized iPhone on Apple Silicon Macs. Unlike the Simulator, this is real iOS with a real kernel, real security boundaries, and real filesystem structure. The tool orchestrates a multi-stage process: downloading IPSW firmware files, applying dozens of binary patches to bypass security mechanisms, flashing the modified firmware via DFU mode, deploying a custom SSH ramdisk, and installing what the project calls Custom Firmware (CFW) with filesystem modifications that persist across reboots.
Technical Insight
The architecture reveals just how locked-down iOS really is. vphone-cli offers three firmware variants with escalating patch counts: Regular (41 boot chain patches + 10 CFW phases), Development (52 patches + 12 CFW phases adding TXM entitlement and debug bypasses), and Jailbreak (112 patches + 14 CFW phases achieving full security bypass). Each variant requires coordinating multiple terminal sessions because different stages need the VM in different states—DFU mode for restore operations, ramdisk mode for filesystem access, and normal boot for the final running system.
The patching process targets specific offsets in iBoot, the kernel, and other boot components. The project’s research documentation provides detailed binary patch comparisons showing exactly what’s being modified at the component level. The tool currently supports iOS 26.x on specific iPhone model 17,3 firmware builds paired with compatible CloudOS versions.
The multi-stage installation process demonstrates the complexity of iOS’s secure boot chain:
# Terminal 1: Boot VM in DFU mode
make boot_dfu
# Terminal 2: Flash patched firmware
make restore_get_shsh
make restore
# Terminal 3: Establish SSH tunnel to ramdisk
iproxy 2222 22
# Terminal 2: Install custom firmware
make cfw_install_jb # 14 phases for jailbreak variantEach stage validates the previous one succeeded before proceeding. The ramdisk deployment is particularly clever—it’s a minimal bootable iOS environment with SSH enabled, allowing the CFW installation scripts to mount the actual system partition and modify it before the first real boot. The jailbreak variant’s CFW runs a LaunchDaemon on first boot (/cores/vphone_jb_setup.sh) that installs Sileo, configures apt repositories, deploys TrollStore, and creates necessary symlinks—essentially completing the jailbreak automatically.
The codebase itself is Swift, using private Virtualization.framework APIs. The private APIs require specific entitlements that Apple doesn’t grant to third-party developers, which is why the tool demands either fully disabling System Integrity Protection or using tools like amfidont to whitelist the vphone-cli binary’s code signature. The Makefile-driven workflow handles dependency installation (via Homebrew), building vendored tools from submodules (trustcache, insert_dylib, libimobiledevice), and orchestrating the firmware download process using aria2c for multi-connection parallel downloads.
VM configuration lives in vm/config.plist, following the same VMBundle.Config format Apple uses in their security-pcc project. This means you can specify CPU cores, memory allocation, and disk size at creation time, and vphone-cli will respect those settings on subsequent boots. The storage backend uses sparse disk images, so a 64GB virtual disk doesn’t immediately consume 64GB of host storage.
Gotcha
The security trade-offs are substantial. Running vphone-cli requires either completely disabling System Integrity Protection or using csrutil enable --without debug combined with AMFI bypass tools. Both approaches weaken your Mac’s security posture significantly. Apple implemented SIP and AMFI specifically to prevent unsigned code execution and kernel extensions—disabling them exposes your system to malware that would otherwise be blocked. This makes vphone-cli unsuitable for daily-driver Macs; you need a dedicated research machine you’re comfortable compromising.
Compatibility is extremely narrow. The tool only supports iOS 26.x builds with specific firmware-to-CloudOS version pairings documented in the tested environments table. The tested environments table shows Mac16,12 hosts running macOS 26.3, and macOS 15+ (Sequoia) is required for PV=3 virtualization. The three-terminal workflow feels fragile—if your DFU boot dies mid-restore, you’re troubleshooting with minimal error messages. The tool assumes you understand IPSW structure, iOS boot chains, and can interpret cryptic restore failures.
Verdict
Use vphone-cli if you’re conducting iOS security research, developing jailbreak tweaks, or analyzing iOS malware in a controlled environment where you need full kernel access and can dedicate a Mac to research with weakened security. The jailbreak variant delivers a genuinely usable virtualized jailbroken iPhone, which is invaluable for testing without risking physical hardware. Skip if you’re doing standard iOS app development (Xcode Simulator is faster and safer), don’t have a spare Mac you can run with SIP disabled, or want a polished tool with comprehensive documentation. This is a power-user research instrument built by reverse engineers for reverse engineers—respect the security implications and complexity before diving in.
