How to Run vphone-cli: A Complete Guide to Virtualizing iOS on macOS

Run vphone-cli by building the Swift binary from source, preparing a patched iOS firmware bundle, and launching a virtual machine using the vphone-cli vm create command.

vphone-cli is a Swift-based command-line tool that creates, patches, and boots virtual iPhones using Apple's Virtualization.framework. The project, hosted at Lakr233/vphone-cli, orchestrates firmware downloads, binary patching, and VM lifecycle management through a hierarchical CLI interface defined in sources/vphone-cli/VPhoneCLI.swift.

Prerequisites and System Requirements

Before you run vphone-cli, ensure your host meets the following requirements:

• macOS 15 or later (Sequoia) is required for full Virtualization.framework compatibility
• Apple Silicon Mac (M-series chip) recommended for optimal performance with the SEP (Secure Enclave Processor) emulation
• Homebrew installed for dependency management
• Approximately 50GB of free disk space for IPSW downloads, extracted firmware, and VM bundles

Install the required host dependencies via Homebrew:

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

Building vphone-cli from Source

vphone-cli must be compiled from source as it requires code signing with private entitlements to interact with the Virtualization.framework. The build process involves two main scripts located in the scripts/ directory.

Clone the Repository and Initialize Submodules

Clone the repository with all submodules to ensure you have the FirmwarePatcher package and guest daemon source:

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

Run the Setup Script

Execute scripts/setup_tools.sh to install sub-modules, download required toolchains, and create the Python virtual environment (.venv) used by the patching pipeline:

./scripts/setup_tools.sh

This script prepares the environment for the firmware patching operations handled by PatchFirmwareCLI in sources/vphone-cli/VPhoneCLI.swift.

Compile and Sign the Binary

Run scripts/build.sh to build the Swift executable, sign it with the necessary entitlements, and bundle the .app structure:

./scripts/build.sh

The compiled binary will be available at .build/vphone-cli.app/Contents/MacOS/vphone-cli. You can either navigate to this directory or add it to your PATH.

Creating and Launching Your First Virtual iPhone

The CLI exposes sub-commands that map to three logical layers: firmware preparation, patching, and VM management. The entry point in sources/vphone-cli/main.swift parses commands and dispatches to handlers like VPhoneVMCommand and VPhoneFWCommand.

Quick Start with One Command

For immediate results, use the high-level shortcut that automates the entire pipeline:

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

The vm create command performs the following actions sequentially:

1. Downloads the appropriate IPSW for the specified variant (here, jb for jailbreak)
2. Executes the FirmwarePipeline (Swift-only implementation in the FirmwarePatcher package) to merge cloudOS and apply binary patches
3. Patches the boot-chain, TXM, and kernel as defined in PatchFirmwareCLI
4. Performs a DFU restore and installs the custom firmware (CFW)

Manual Firmware Pipeline (Alternative)

For fine-grained control over the patching process, execute each stage manually:

# Initialize an empty VM bundle

vphone-cli vm new myphone

# Download and prepare firmware for iOS 26.1

vphone-cli fw prepare myphone --iphone-version 26.1

# Apply jailbreak patches

vphone-cli fw patch myphone --variant jb

# Boot into DFU mode for restoration (backgrounded)

vphone-cli vm launch myphone --dfu &

# Capture SHSH blobs and perform DFU restore

vphone-cli restore myphone --get-shsh
vphone-cli restore myphone

# Stop the DFU boot process

vphone-cli vm stop myphone

# Install custom firmware (requires sudo for mounting)

vphone-cli cfw install myphone --variant jb

# Final boot into normal GUI mode

vphone-cli vm launch myphone

This manual approach lets you inspect intermediate artifacts and customize patch parameters defined in research/0_binary_patch_comparison.md.

Managing the Virtual Machine Lifecycle

Once built, VMs are managed through VPhoneVirtualMachine.swift, which wraps VZVirtualMachineConfiguration to configure CPU, memory, disk, SEP, and screen parameters.

Booting in Different Modes

vphone-cli supports multiple boot modes via the VPhoneVirtualMachine class:

• GUI Mode: Default interactive mode with graphical display (requires NSApplication lifecycle as implemented in main.swift)
• DFU Mode: Headless device firmware update mode for restoration operations (--dfu flag)
• Headless Mode: Background operation without display attachment

Stop a running VM gracefully:

vphone-cli vm stop myphone

Connecting to the Running Instance

After launching, connect to your virtual iPhone using standard networking:

# SSH as mobile user (jailbreak environment, password: alpine)

ssh -p 22222 mobile@<vm-ip>

# SSH as root (development environment)

ssh -p 22222 root@<vm-ip>

# VNC graphical console

open vnc://<vm-ip>:5901

The SSH and VNC services are forwarded through the virtual network interface configured by VZVirtualMachine.

Summary

• vphone-cli is a Swift CLI tool for virtualizing iOS on macOS 15+ using Apple's Virtualization.framework.
• Build process relies on scripts/setup_tools.sh for dependencies and scripts/build.sh for compilation and code signing.
• Firmware pipeline in sources/vphone-cli/VPhoneCLI.swift handles IPSW downloads, binary patching (TXM, kernel, boot-chain), and bundle creation.
• VM lifecycle is managed via VPhoneVirtualMachine.swift, supporting GUI, DFU, and headless boot modes.
• Quick start uses vphone-cli vm create <name> -V <variant> to automate the entire workflow.
• Access methods include SSH on port 22222 (mobile/alpine or root) and VNC on port 5901.

Frequently Asked Questions

What macOS version do I need to run vphone-cli?

You need macOS 15 (Sequoia) or later. The tool depends on specific APIs in Apple's Virtualization.framework that are only available in macOS 15+, particularly for SEP (Secure Enclave Processor) emulation and the PV (Platform Version) 3 virtualization layer.

How do I jailbreak the virtual iPhone?

Use the jb variant flag during creation or patching: vphone-cli vm create myphone -V jb or vphone-cli fw patch myphone --variant jb. According to the source code in VPhoneCLI.swift, this applies the jailbreak-specific binary patches to the kernel and userspace components, enabling the mobile user SSH access with password alpine on port 22222.

Can I run multiple virtual iPhones simultaneously?

While the Virtualization.framework supports multiple VMs, vphone-cli manages VM state through named bundles in the working directory. Each VM requires significant resources (disk, memory, CPU cores). You can create multiple instances with different names using vphone-cli vm new <name>, but ensure your host has sufficient RAM and CPU overhead for concurrent SEP emulation.

Where are the VM bundles and firmware stored?

VM bundles are created as directories in your current working directory when you run vphone-cli vm new or vphone-cli vm create. These bundles contain the virtual disk images, NVRAM, and configuration. Downloaded IPSWs and intermediate patched firmware components are cached within the project structure or system temp directories, depending on the FirmwarePipeline implementation in the FirmwarePatcher package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}