Lakr233/vphone-cli: Virtual iOS 26 on macOS with Virtualization.framework

Lakr233/vphone-cli: Virtual iOS 26 on macOS with Virtualization.framework

Testing iOS applications traditionally requires physical hardware or limited simulators that don't replicate real device behavior. Developers working on security research, automation pipelines, or compatibility testing face friction: provisioning devices, managing firmware versions, and isolating test environments. Lakr233/vphone-cli addresses this by booting virtual iPhones directly on macOS through Apple's native Virtualization.framework, leveraging the same Private Compute Cloud (PCC) research VM infrastructure Apple uses internally.

This tool isn't an emulator or simulator—it's a full virtualization stack that runs actual iOS firmware with varying levels of modification, from near-stock configurations to fully jailbroken environments with SSH and package management. For developers who need reproducible iOS environments without hardware sprawl, vphone-cli offers a technically distinctive approach worth understanding.

What is Lakr233/vphone-cli?

Lakr233/vphone-cli is an open-source Swift project (7,108 GitHub stars, 1,051 forks, MIT License) that virtualizes iPhones on Apple Silicon Macs running macOS 15+. It uses Virtualization.framework with PV=3 virtualization support—Apple's paravirtualization tier that provides near-native performance for guest operating systems. The project implements the PCC (Private Compute Cloud) research VM infrastructure, which Apple developed for secure, isolated iOS compute environments.

The tool's last commit was July 13, 2026, indicating active maintenance. It supports iOS versions from 18.x through 26.x, with explicit compatibility matrices for host macOS builds and specific iPhone firmware identifiers (e.g., 17,3_26.5.2_23F84 for iPhone 17,3 hardware running iOS 26.5.2).

What distinguishes vphone-cli from Xcode's iOS Simulator is fundamental: it runs actual iOS firmware images (IPSW files), not a compiled-for-macOS userspace. This means real kernel behavior, actual sandbox enforcement, and genuine hardware-adjacent execution paths. The trade-off is complexity—you're managing firmware downloads, boot chain patches, and security bypasses rather than clicking "Run" in Xcode.

The project offers five firmware patch variants, from minimal intervention (4 patches, "Patchless") to extensive kernel and dynamic shared cache modification (141 patches, "Experimental"). This granularity matters for different use cases: security researchers need deep access, while app developers might want something closer to stock iOS behavior.

Key Features

Native Virtualization Stack: vphone-cli builds on Virtualization.framework rather than third-party hypervisors, avoiding the performance and compatibility penalties of emulation layers like QEMU. The PV=3 requirement means it targets Apple's latest paravirtualization APIs introduced in macOS Sequoia.

Five Firmware Variants: The patch spectrum is technically significant:

• Patchless (4 patches): Minimal boot chain modification, preserves most security boundaries
• Regular (42 patches): Standard CFW installation with moderate security bypasses
• Development (53 patches): Adds TXM entitlement and debug path enablement
• Jailbreak (113 patches): Full security bypass with automatic Sileo/TrollStore installation via LaunchDaemon
• Experimental (141 patches): Jailbreak superset that spoofs VM identity to Apple services while preserving paravirtualized GPU/compute paths

GPU/Metal Passthrough Limitations: The documentation is notably honest about constraints. iOS 18.x lacks paravirtualized GPU implementation in its Metal/IOGPU framework, so Metal-rendered content (web pages, images, wallpapers) fails to render. Touch, networking, and app execution work normally. iOS 26.x improves this situation.

Host Control Socket for Automation: A Unix domain socket (vm/vphone.sock) exposes programmatic control—screenshots, touch injection, swipes, hardware key simulation, and clipboard access. Every action returns a grayscale screenshot, enabling computer-vision-driven test automation. The companion vphone-mcp project wraps this as an MCP (Model Context Protocol) server for AI agent integration.

VM Backup and Switching: Sparse disk handling via rsync --sparse allows efficient snapshots of entire environments, useful for testing across iOS versions or maintaining clean baselines versus modified states.

Use Cases

iOS Security Research: The Experimental variant's ability to mask VM identity while keeping paravirtualized paths functional is specifically designed for researchers analyzing Apple's service-side behavior. The automatic jailbreak setup with Sileo package management provides familiar tooling for vulnerability analysis.

Automated UI Testing: The control socket's screenshot-every-action design suits end-to-end testing pipelines. Unlike XCTest UI testing, which runs within iOS's automation framework, vphone-cli operates from the host—enabling tests that survive app crashes, springboard restarts, or OS-level state changes.

Cross-Version Compatibility Validation: The backup/switch mechanism lets teams maintain environments across iOS 26.0 through 26.5.x simultaneously. For developers supporting wide iOS version ranges, this eliminates physical device procurement for each minor OS release.

CI/CD for iOS Builds: While not explicitly documented for CI use, the Makefile-driven workflow and non-interactive options (NON_INTERACTIVE=1 SUDO_PASSWORD=...) suggest headless operation is intended. The make setup_machine target automates the entire flow from firmware download through first boot.

Private Compute Cloud Development: Teams building on Apple's PCC infrastructure directly can use vphone-cli as a local development environment before cloud deployment, matching the same VM configuration format.

Installation & Setup

Host requirements are strict: macOS 15+ (Sequoia) with Apple Silicon, plus SIP/AMFI configuration for private Virtualization.framework entitlements.

SIP/AMFI Configuration (Choose One Path)

Option 1: Fully disable SIP + AMFI (most permissive)

Boot into Recovery (long-press power button), open Terminal:

csrutil disable
csrutil allow-research-guests enable

After restarting into macOS:

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

Restart once more.

Option 2: Keep SIP mostly enabled, disable debug restrictions only

In Recovery:

csrutil enable --without debug
csrutil allow-research-guests enable

After restarting, use amfidont or amfree:

# Using amfidont
xcrun python3 -m pip install amfidont
sudo amfidont --path [PATH_TO_VPHONE_DIR]

# OR using amfree
brew install retX0/tap/amfree
sudo amfree --path [PATH_TO_VPHONE_DIR]

Repository helper for amfidont:

make amfidont_allow_vphone

The Patchless variant requires Option 1 or amfidont with -S flag: sudo amfidont -S --path [PATH_TO_VPHONE_DIR]

Dependencies

brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd

Clone with submodules (required for vendored dependencies and toolchain sources):

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

Real Code Examples

Automated Full Setup

The make setup_machine target orchestrates the complete workflow:

make setup_machine            # full automation through "First Boot"
# options: NON_INTERACTIVE=1 SUDO_PASSWORD=...
# LESS=1 for patchless variant
# DEV=1 for dev variant
# JB=1 for jailbreak variant
# EXP=1 for experimental variant
# SPOOF_BUILD=<id> (EXP only) - e.g., SPOOF_BUILD=23F77

This single command handles tool installation, firmware download, patching, VM creation, restore, CFW installation, and first boot. The variant flags select which patch level to apply—critical because each variant trades security bypass depth against detection risk.

Manual VM Creation with Custom Resources

make vm_new CPU=16 MEMORY=16384 DISK_SIZE=128

Configuration persists in vm/config.plist in the security-pcc VMBundle.Config format. Subsequent make boot reads this automatically.

SSH Tunnel Setup for Remote Access

After jailbreak variant installation, forward services via usbmux:

python3 -m pymobiledevice3 usbmux forward 2222 22222    # SSH (dropbear)
python3 -m pymobiledevice3 usbmux forward 2222 22       # SSH (openssh-server from Sileo)
python3 -m pymobiledevice3 usbmux forward 5901 5901     # VNC
python3 -m pymobiledevice3 usbmux forward 5910 5910     # RPC

Connect via:

• SSH (JB): ssh -p 2222 mobile@127.0.0.1 (password: alpine)
• SSH (Regular/Dev): ssh -p 2222 root@127.0.0.1 (password: alpine)
• VNC: vnc://127.0.0.1:5901

VM Environment Management

make vm_backup NAME=26.1-clean    # save current VM state
rm -rf vm && make vm_new          # start fresh
# ... prepare, patch, restore, install, boot ...
make vm_backup NAME=26.3-jb       # save new environment
make vm_list                      # enumerate backups
make vm_switch NAME=26.1-clean    # restore previous state

The rsync --sparse handling preserves disk efficiency—empty blocks in the VM image don't consume backup space.

Advanced Usage & Best Practices

Region Selection During Setup: The FAQ documents a specific pitfall—selecting Japan or EU regions during iOS setup triggers regulatory checks (sideloading disclosures, camera shutter requirements) that fail in virtualized environments. Choose United States or other regions to avoid system app download failures.

Offline Restore Considerations: make restore_offline decrypts AEA images locally but requires internet for the first AEA decryption. If stuck at setup after offline restore, supervise the device to bypass most setup screens:

python3 -m pymobiledevice3 profile supervise vphone

Host Key Generation for Non-JB Variants: The Regular and Development variants require manual SSH host key creation. Without this, dropbear accepts connections then immediately closes them—no error message indicates the root cause:

dropbearkey -t rsa -f /var/dropbear/dropbear_rsa_host_key
dropbearkey -t ecdsa -f /var/dropbear/dropbear_ecdsa_host_key

Nested Virtualization Detection: The tool now fails fast via boot_binary_check when running inside an Apple VM (kern.hv_vmm_present=1). Don't attempt deployment on cloud macOS instances unless they provide bare-metal access.

Comparison with Alternatives

vphone-cli vs. Xcode Simulator: The Simulator runs recompiled binaries against macOS's frameworks—fast, but behavior diverges from real iOS in sandboxing, entitlement handling, and kernel interactions. vphone-cli runs genuine firmware at the cost of setup complexity.

vphone-cli vs. Corellium: Corellium offers broader device support and easier cloud deployment but operates in legal gray areas regarding Apple's IP. vphone-cli uses Apple's own frameworks and publicly available IPSWs, with clearer licensing posture.

vphone-cli vs. Physical Devices: Physical hardware provides authentic sensors, cellular radios, and App Store compliance. vphone-cli trades these for reproducibility, snapshotting, and programmatic control—ideal for automation, less so for sensor-dependent or carrier-specific testing.

FAQ

Q: Why does ./vphone-cli get killed immediately? AMFI restrictions aren't bypassed. Use full AMFI disable via nvram boot-args or configure amfidont/amfree with proper path allowlisting.

Q: Can I run this in a cloud Mac instance? No. Nested Virtualization.framework is unsupported. The tool detects kern.hv_vmm_present=1 and fails before VM startup.

Q: What's the difference between Jailbreak and Experimental variants? Experimental adds 28 patches that spoof VM identity to Apple services while preserving paravirtualized GPU/compute paths. Jailbreak variant doesn't mask virtualization.

Q: Is GPU acceleration fully working? iOS 26.x has functional paravirtualized GPU support. iOS 18.x lacks this—Metal-rendered content won't display, though touch and networking function.

Q: How do I update to newer iOS versions? Override IPSW sources and re-run the patch workflow. Binary analysis-based patches (not static offsets) should adapt automatically.

Q: What's the license? MIT License—permissive for commercial and research use.

Q: Can I install enterprise or sideloaded apps? The jailbreak variant includes TrollStore, which handles .tipa installations. The install menu also supports standard .ipa files.

Conclusion

Lakr233/vphone-cli occupies a specific niche: developers and researchers who need genuine iOS execution with host-level automation, on Apple Silicon hardware, without cloud virtualization services. The five patch variants provide unusual granularity in security posture, from near-stock behavior to deeply modified research environments.

The tool rewards users comfortable with firmware management, kernel patching concepts, and macOS security configuration. It's not a drop-in Simulator replacement for casual app development, but for security research, automated testing pipelines, and PCC infrastructure development, it provides capabilities unavailable elsewhere in the open-source ecosystem.

The active maintenance (July 2026 last commit), substantial community interest (7,108+ stars), and companion projects like vphone-mcp suggest this is a maturing platform rather than a proof-of-concept. If your work involves iOS automation, virtualization research, or cross-version compatibility testing, explore the repository and evaluate which firmware variant matches your threat model and technical requirements.