vphone-cli: Virtual iPhone CLI Running Real iOS Firmware on Apple Silicon Mac

When testing iOS applications or verifying low-level system behaviors on Apple Silicon Macs, developers have traditionally relied on tethered physical test devices or navigated the architecture and runtime limitations of high-level Xcode simulators. The open-source command-line tool vphone-cli introduces an alternative virtualization approach by utilizing Apple's native Virtualization.framework to create and boot virtual iPhone instances directly from genuine iOS firmware (IPSW) restore images.

Image source: Lakr233 / GitHub

By automating the entire workflow from firmware preparation to virtual device control through a single terminal pipeline, vphone-cli provides iOS security researchers, system platform developers, and automated testing engineers with a reproducible, software-defined test environment without requiring physical hardware fleets.

Beyond Xcode Simulators: Real iOS Firmware Virtualization Architecture

Standard Xcode simulators operate by running macOS-targeted x86_64 or ARM64 binaries on top of the host macOS kernel via high-level API emulation. While efficient for routine UI layout and app development, this architecture cannot accurately reproduce low-level iOS sandbox constraints, kernel exploit behaviors, or genuine operating system daemon workflows.

vphone-cli addresses this gap by interfacing directly with Apple's Virtualization.framework on Apple Silicon Macs to execute a complete, self-contained iOS operating system inside a virtual machine.

• Real IPSW Firmware Execution: Rather than deploying a mocked development container, the tool mounts and boots official iOS restore images (IPSW), ensuring native system processes and background services run faithfully.
• Isolated Virtualized Sandboxes: System modifications and test routines remain quarantined inside the virtual machine, allowing developers to experiment with low-level components without risking host stability.

This eliminates the logistics of managing dedicated physical devices or USB device farms, establishing a reproducible local environment where developers can spin up clean iOS instances on demand.

Automated Pipeline: DFU Restore, Remote Access, and E2E/AI Automation

The key technical advantage of vphone-cli is its fully unified command-line pipeline, which eliminates the manual setup typically required when orchestrating firmware-level virtual machines.

The tool coordinates every phase of provisioning and operational interaction through straightforward CLI commands:

• End-to-End Automated Provisioning: Handles downloading official IPSW firmware, applying bootchain patches, executing virtual DFU (Device Firmware Upgrade) restoration, and conducting the initial boot sequence within a single pipeline.
• Remote Access and Monitoring: Provides immediate SSH access for terminal-based shell operations and remote debugging, alongside VNC display connectivity to view and interact with the graphical user interface.
• Automation and AI Integration: Features snapshot cloning, import/export facilities, and programmable input hooks—including screenshot capture, screen taps, swipes, and physical hardware button events—enabling direct integration with automated E2E test suites and AI agent harnesses such as vphone-mcp.

This programmatic input layer makes the tool suitable not only for manual inspection, but also as an execution substrate for autonomous LLM agents that observe screen state and interact with iOS applications.

Multi-Tier Patch Variants, System Requirements, and Security Caveats

To accommodate diverse development and security auditing requirements, vphone-cli provides configurable firmware patching tiers:

• Three Patch Variants: Supports a Regular mode for standard iOS behavioral checks, a Development mode offering extended debugging instrumentation, and a Jailbreak mode intended for low-level platform analysis and security research.

Because the tool interacts with low-level virtualization primitives and bootchain components, specific system requirements and security considerations must be observed:

• Hardware and OS Prerequisites: An Apple Silicon Mac (M1 chip or newer) running macOS 15 or later with a current Xcode installation is strictly required.
• Operational Security Considerations: Enabling jailbreak patch variants and low-level virtualization hooks may require disabling host System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI). Because relaxing these protections lowers macOS system safeguards, this workflow is intended specifically for dedicated research and isolated development machines rather than everyday production environments.

Sources

• GitHub Repository: Lakr233/vphone-cli - Open-source command-line tool for virtualizing real iOS firmware on Apple Silicon Macs
• X (Twitter) Announcement: @Ryrenz Post - Release announcement and feature demonstration for vphone-cli