How to Boot a Virtual iPhone on Apple Silicon Using vphone-cli: A Complete Guide

Boot a virtual iPhone on Apple Silicon by running make boot after building vphone-cli, creating a VM, preparing and patching iOS firmware, and allowing the signed binary through AMFI.

vphone-cli is a Swift-based open-source project that orchestrates the full lifecycle of a virtual iPhone (platform version 3) on Apple Silicon Macs. This guide walks through the complete boot sequence from source code to running VM, referencing the actual build system and Swift implementation in the Lakr233/vphone-cli repository.

Prerequisites for Running vphone-cli

Before booting a virtual iPhone, your host system must meet strict requirements. The tool is designed exclusively for macOS 15 (Sequoia) on Apple Silicon and requires disabled System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI). These restrictions exist because vphone-cli relies on private virtualization entitlements defined in vphone.entitlements that Apple does not grant to standard developers.

Begin by installing the toolchain:

make setup_tools

This target installs Homebrew dependencies, trustcache utilities, insert_dylib, and a Python virtual environment required for firmware manipulation.

Building the vphone-cli Binary

The build process compiles Swift sources, injects version metadata, and signs the binary with custom entitlements. In Makefile, the $(BINARY) target handles compilation at lines 17-26.

make build

The build system generates VPhoneBuildInfo.swift with the current Git hash, then codesigns the resulting binary with vphone.entitlements. This signing step is critical—the private entitlement enables the virtual machine to use Apple's private virtualization APIs.

Creating a VM Directory

Every virtual iPhone requires an isolated VM folder containing config.plist for hardware parameters. The vm_new target creates this structure at vm/ by default:

make vm_new

Default values are 8 CPU cores, 8192 MiB RAM, and 64 GiB disk size. The config.plist format follows Apple's VZVirtualMachineConfiguration schema and is parsed later by VPhoneVMPicker.swift when the VM starts.

Preparing iOS Firmware

The firmware preparation stage downloads and merges IPSW components for the target device. By default, vphone-cli targets iPhone17,3:

make fw_prepare

This invoke scripts/fw_prepare.sh, which performs three operations:

• Downloads the IPSW from Apple's CDN
• Extracts the filesystem and kernelcache
• Merges CloudOS components into a unified firmware tree

The output is a pristine iOS image ready for patching.

Patching the Boot Chain

vphone-cli supports three firmware variants selected via separate Makefile targets. First build the patcher tool:

make patcher_build

Then apply patches based on your use case:

Target	Description	Patches
make fw_patch	Regular variant	52 patches for basic virtualization
make fw_patch_jb	Jailbreak variant	Adds jetsam fixes and Procursus environment
make fw_patch_exp	Experimental variant	Includes hv_vmm rename and device tree identity tweaks

The patcher binary receives --variant flags corresponding to each target. See fw_patch* rules at lines 52-80 of the Makefile for implementation details.

Installing Custom Firmware (CFW)

After patching, install the modified firmware onto the VM disk. Three matching targets correspond to the patch variants:

make cfw_install      # Regular CFW

make cfw_install_jb   # CFW with jailbreak

make cfw_install_exp  # CFW with research patches

The underlying cfw_install_host target (lines 78-98) mounts the VM directory, flips the boot snapshot for write access, and copies patched kernelcache and filesystem images using scripts/cfw_install_host.sh.

Bypassing AMFI for the Signed Binary

macOS blocks binaries with private entitlements by default. The repository includes an AMFI bypass helper that must be built and executed:

make amfidont_allow_vphone

This target first builds the helper bundle, then runs scripts/start_amfidont_for_vphone.sh to temporarily disable AMFI checks for the vphone binary. Without this step, the boot process fails immediately with a codesigning error.

Booting the Virtual iPhone

Three boot modes are available through the Makefile:

make boot       # Normal boot with vphoned daemon

make boot_less  # Boot without vphoned (patch-less compatibility)

make boot_dfu   # DFU mode for restore operations

The boot target performs a complete pre-flight sequence defined at lines 28-35 of the Makefile:

1. Builds the app bundle if stale
2. Verifies vphoned daemon presence
3. Runs binary validation checks
4. Executes the signed binary with the VM's config.plist

Command-line argument parsing occurs in sources/vphone-cli/main.swift at lines 9-14, which routes the boot subcommand to VPhoneAppDelegate. This class initializes VPhoneVirtualMachine, which wraps VZVirtualMachineConfiguration and manages the actual virtualization lifecycle through Apple's Virtualization framework.

# Complete sequence for a jailbroken virtual iPhone

make setup_tools
make build
make vm_new
make fw_prepare
make fw_patch_jb
make cfw_install_jb
make amfidont_allow_vphone
make boot

Summary

• Prerequisites: macOS 15, Apple Silicon, SIP/AMFI disabled, and toolchain via make setup_tools
• Build: make build creates a signed binary with private entitlements
• VM Setup: make vm_new generates config.plist with hardware specifications
• Firmware: make fw_prepare downloads IPSW; patch variants add jailbreak or experimental features
• Installation: make cfw_install* flashes patched firmware to the VM disk
• Boot: make boot launches the virtual iPhone through VPhoneAppDelegate and VZVirtualMachine

Frequently Asked Questions

What macOS version is required for vphone-cli?

vphone-cli requires macOS 15 (Sequoia). The tool relies on virtualization APIs and entitlement formats introduced in this release, and earlier versions lack the necessary VZVirtualMachine capabilities for iOS virtualization.

Why does vphone-cli need SIP and AMFI disabled?

The signed binary uses a private entitlement (vphone.entitlements) that Apple restricts to internal development. macOS normally rejects such binaries; disabling SIP and AMFI allows the system to load the entitlement and grant access to private virtualization APIs.

What is the difference between boot, boot_less, and boot_dfu?

make boot runs the full stack including the vphoned daemon for enhanced functionality. make boot_less skips the daemon for compatibility with unpatched or minimally modified firmware. make boot_dfu enters Device Firmware Update mode, enabling restore operations through iTunes or Finder.

Can I change the virtual iPhone model from iPhone17,3?

The default device identifier is hardcoded in scripts/fw_prepare.sh and related patch configurations. Modifying it requires adjusting multiple components including the IPSW download URL, device tree patches, and potentially the hardware model passed to VZVirtualMachineConfiguration in VPhoneVirtualMachine.swift.

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