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

> Learn to boot a virtual iPhone on Apple Silicon with vphone-cli. Follow our guide to build, prepare firmware, and run iOS on your Mac for development and testing.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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:

```bash
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.

```bash
make build

```

The build system generates [`VPhoneBuildInfo.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`:

```bash
make fw_prepare

```

This invoke [`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
make amfidont_allow_vphone

```

This target first builds the helper bundle, then runs [`scripts/start_amfidont_for_vphone.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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`:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift).