vphone-cli

Product Introduction

1. Definition: vphone-cli is a command-line interface (CLI) tool and software framework for creating and managing fully virtualized iPhone instances (VMs) on Apple Silicon Macs. It is a developer tool that leverages Apple's native Virtualization.framework and the proprietary PCC (Platform Certificate Chain) research VM infrastructure to boot a complete iOS system.
2. Core Value Proposition: It solves the critical need for accessible, high-fidelity iOS virtualization for development, testing, and security research. It provides developers and researchers with disposable, sandboxed iPhone environments without requiring physical hardware, enabling efficient testing of SMS authentication, push notifications, app integrations, and deep system-level analysis.

Main Features

1. End-to-End VM Pipeline: The tool automates the entire process from a bare command to a running virtual iPhone. The vphone-cli vm create command handles downloading iPhone and cloudOS IPSW firmware files, patching the boot chain, performing a DFU restore, and installing a custom firmware (CFW) variant. This automation eliminates the complex, manual steps typically associated with iOS virtualization.
2. Configurable Patch Variants: vphone-cli offers a tiered system of firmware patches, defined by the --variant flag (less, regular, dev, jb, exp). These variants apply an increasing number of binary patches to the iOS kernel and system components, progressively bypassing security mitigations like AMFI (Apple Mobile File Integrity), SSV (Signed System Volume), and enabling full jailbreak capabilities with package managers like Sileo pre-installed in the jb variant.
3. Programmatic Control Socket: For automation and integration, each running VM exposes a Unix domain socket (<bundle>/vphone.sock). This API allows for programmatic control of the virtual device, enabling actions like simulating touch inputs, hardware button presses, taking screenshots, and manipulating the clipboard. This is essential for AI-driven end-to-end testing and CI/CD pipelines.
4. Efficient VM Management: The CLI provides a full suite of lifecycle management commands. Users can clone VM bundles using fast APFS copy-on-write, export/import compressed VM states, configure CPU core and memory allocation, and connect via SSH (port 22222) or VNC (port 5901) for direct interaction. Library management is centralized under ~/.vphone/ for cache and VM storage.

Problems Solved

1. Pain Point: The high cost and logistical complexity of procuring and maintaining multiple physical iOS devices for development and quality assurance testing, especially for features requiring unique device IDs or phone numbers.
2. Target Audience: iOS and cross-platform mobile developers, QA automation engineers, DevOps professionals building CI/CD pipelines for mobile apps, and security researchers conducting iOS kernel or application vulnerability analysis.
3. Use Cases: Testing SMS-based two-factor authentication (2FA) flows, verifying push notification delivery and handling, automating UI tests for different iOS versions, staging server-to-device communication, and researching iOS internals or exploit development in a safe, isolated sandbox.

Unique Advantages

1. Differentiation: Unlike cloud-based iOS device farms or simulator-like environments, vphone-cli runs a real, full iOS system stack virtualized locally. It provides higher fidelity than the iOS Simulator (which runs a x86_64 userland) and more control and lower cost than physical device labs or third-party cloud services.
2. Key Innovation: Its core innovation is the automated patching and repackaging of official Apple IPSW firmware files to run on the Virtualization.framework with PCC research extensions. The tiered variant system (jb, exp) which applies over 100 specific binary patches to enable jailbroken and research-ready environments directly from stock IPSWs is a significant technical achievement.

Frequently Asked Questions (FAQ)

1. What are the system requirements for running vphone-cli? You need an Apple Silicon Mac (M-series) running macOS 15 Sequoia or later, with Xcode and the iOS SDK installed. System Integrity Protection (SIP) must be partially or fully disabled, and AMFI restrictions relaxed via a boot-arg or the included vphone-amfidont tool to allow the necessary kernel entitlements.
2. Can vphone-cli run on an Intel Mac or within a macOS virtual machine? No. It requires the Virtualization.framework with PCC support, which is only available on Apple Silicon hosts. Furthermore, it cannot run in a nested virtualization scenario (e.g., a macOS VM on a Mac); the host must be bare-metal.
3. How do I install applications (.ipa files) onto a vphone-cli virtual iPhone? For jailbroken variants (jb, exp), you can use the pre-installed package manager. For all variants, you can use the VM's graphical "Install" menu via VNC to drag-and-drop or select .ipa or .tipa files for installation.
4. What does the "Stuck on 'Press home to continue'" error mean and how do I fix it? This is a common setup step in the iOS activation process. You must connect to the VM using a VNC client (e.g., vnc://<vm-ip>:5901) and perform a right-click (or two-finger click on a trackpad) to simulate pressing the virtual Home button.
5. Why does the cfw install command sometimes hang or use excessive memory? This is a known bug in specific versions of ldid-procursus, the tool used to re-sign binaries with entitlements. It occurs when processing entitlements containing an integer value of 0. The solution is to update to the latest HEAD version: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus.