vphone-cli: Boot Virtual iPhones on Apple Silicon with Advanced Control

Introduction

vphone-cli is an innovative command-line tool designed to boot virtual iPhones on Apple Silicon Macs. It utilizes Apple's Virtualization.framework, building upon the PCC research VM infrastructure to offer a robust and flexible environment for iOS virtualization. This project provides extensive control over virtual iOS devices, enabling users to perform tasks ranging from standard VM operations to advanced custom firmware installations.

Key features include support for various firmware variants with increasing security bypass levels, such as less, regular, dev, jb (jailbreak), and exp (experimental). It also offers SSH and VNC connectivity for seamless interaction, making it an invaluable tool for mobile security research, development, and testing.

Why Use and Benefits

vphone-cli offers several compelling advantages for anyone needing to work with virtual iOS environments:

• Comprehensive Control: Gain full command over virtual iPhones, from creation and configuration to launching and stopping, all through a powerful CLI.
• Custom Firmware Support: Install custom firmware (CFW) with different levels of security bypass, including full jailbreak capabilities, providing unparalleled flexibility for research and development.
• Automation: Automate the entire VM lifecycle, from downloading and patching IPSWs to DFU restore and CFW installation, streamlining complex workflows.
• Debugging and Research: Access advanced debugging features and research patches, making it an excellent platform for security analysis and vulnerability research.
• Connectivity: Easily connect to your virtual iPhone via SSH for command-line access or VNC for a graphical interface, facilitating interaction and testing.
• Open Source: Released under the MIT License, promoting transparency and community contributions.

Installation

To get started with vphone-cli, ensure you meet the prerequisites and follow the installation steps.

Prerequisites:

• Host: Apple Silicon Mac, macOS 15+ (Sequoia), Xcode + iOS SDK.
• SIP/AMFI relaxation: Required to allow private PV=3 entitlements with unsigned binaries. Refer to the official repository's README for detailed instructions on csrutil and amfi_get_out_of_my_way or vphone-amfidont.

Dependencies:

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

Install via Homebrew:

brew install zqxwce/tap/vphone-cli

Build from Source:

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

./scripts/setup_tools.sh      # install deps, build toolchain submodules, create the Python venv
./scripts/build.sh            # build + sign vphone-cli, bundle the .app, cross-compile vphoned

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

Examples

Here are some quick examples to demonstrate how to use vphone-cli.

Quick Start: Create and Launch a Jailbroken VM

This command creates a VM end-to-end, including download, patch, DFU restore, CFW install, and first boot.

vphone-cli vm create myphone -V jb
vphone-cli vm launch myphone

Manage Virtual Machines

vphone-cli vm list                         # list VMs
vphone-cli vm info myphone                  # show one VM
vphone-cli vm new myphone                   # create an empty bundle
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # fast APFS clone
vphone-cli vm export myphone --out myphone.tzst   # export VM
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

Build a VM Manually

For granular control, you can build a VM step-by-step.

vphone-cli vm new myphone                              # 1. empty bundle
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. download + merge IPSWs
vphone-cli fw patch myphone --variant jb                # 3. patch the boot chain

vphone-cli vm launch myphone --dfu &                    # 4. boot into DFU (background)
vphone-cli restore myphone --get-shsh                   #    fetch SHSH
vphone-cli restore myphone                              #    DFU restore
vphone-cli vm stop myphone                              #    stop the DFU boot

vphone-cli cfw install myphone --variant jb             # 5. install CFW (host-mount; asks for sudo)
vphone-cli vm launch myphone                            # 6. first boot

Connecting to the VM

• SSH (jailbreak): ssh -p 22222 mobile@<vm-ip> (password alpine)
• SSH (regular/dev): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

Links

• GitHub Repository: https://github.com/Lakr233/vphone-cli