Prerequisites for Running vphone-cli on Apple Silicon: Complete Setup Guide

To run vphone-cli on Apple Silicon, you need an ARM-based Mac running macOS 15 (Sequoia) or later, Xcode with iOS SDK, specific Homebrew dependencies, and relaxed SIP/AMFI security settings to allow private Virtualization.framework entitlements.

The Lakr233/vphone-cli project is a macOS-specific tool that boots a virtual iPhone using Apple's Virtualization.framework with PV=3 (private virtualization) entitlements. Meeting these prerequisites for running vphone-cli on Apple Silicon ensures the host can execute the unsigned binary and manage iOS guest VMs through private APIs that are exclusive to ARM-based hardware.

Hardware and Operating System Requirements

Apple Silicon Mac (ARM64)

vphone-cli requires a genuine Apple Silicon Mac (M1, M2, M3, or later). The tool leverages PV=3 entitlements that are exclusively available on physical ARM-based Apple Silicon hardware. According to the source code in sources/vphone-cli/VPhoneVirtualMachine.swift, this virtualization mode cannot be nested inside another virtual machine, making bare-metal Apple Silicon mandatory.

macOS Sequoia 15 or Later

You must run macOS 15 (Sequoia) or newer. The project depends on Virtualization.framework v2, which introduced support for PV=3 APIs specifically in macOS 15. Earlier macOS releases lack the necessary private frameworks to instantiate the virtual iPhone hardware configuration.

Security and Entitlement Prerequisites

Private Virtualization (PV=3) Access

As implemented in sources/vphone-cli/VPhoneVirtualMachine.swift, the Swift code uses the Dynamic library to call private Virtualization.framework APIs at runtime. This avoids compile-time linking against restricted symbols, but still requires the host system to permit unsigned code with research entitlements.

SIP and AMFI Relaxation Options

Because PV=3 entitlements are private and undocumented, the vphone-cli binary must run with signatures that macOS typically blocks. The repository provides two approaches in the documentation:

Option A: Disable SIP and AMFI Fully disable System Integrity Protection (SIP) and set the amfi_get_out_of_my_way=1 boot argument:

csrutil disable && csrutil allow-research-guests enable
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

Option B: Use vphone-amfidont with SIP Enabled Keep SIP partially enabled while whitelisting the binary using the provided helper:

csrutil enable --without debug
csrutil allow-research-guests enable
vphone-amfidont  # Provided in the app bundle

Development Tools and Dependencies

Xcode and iOS SDK

You need Xcode installed with the iOS SDK. The build process in scripts/build.sh cross-compiles the guest daemon vphoned for iOS architecture during the host build pipeline. Without Xcode's toolchain, the Swift compiler cannot generate the universal binaries required for the virtual iPhone environment.

Required Homebrew Packages

The Python-based patcher and supporting toolchain require several command-line utilities. Install them via Homebrew:

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

These tools handle IPSW downloading, binary patching (ldid-procursus), and firmware extraction.

Build Environment Configuration

Python Virtual Environment Setup

The scripts/setup_tools.sh script creates a dedicated Python virtual environment (.venv) installing specific packages required for binary manipulation:

• capstone
• keystone-engine
• pyimg4

Run ./scripts/setup_tools.sh to initialize this environment before building.

Swift Build and Code Signing

The scripts/build.sh script compiles the Swift binary, applies ad-hoc code signatures, and cross-compiles the iOS guest daemon. The resulting executable resides at .build/vphone-cli.app/Contents/MacOS/vphone-cli. The build process referenced in the repository's Makefile (make build) orchestrates these steps automatically.

Step-by-Step Installation

Follow this sequence to satisfy all prerequisites and build the project:

1. Install dependencies and ensure macOS 15+ is active:

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

2. Configure security settings (choose Option A or B from above). For development, Option A is typically used:

   csrutil disable
   csrutil allow-research-guests enable
   sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

3. Clone and build the repository:

   git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
   cd vphone-cli
   ./scripts/setup_tools.sh
   ./scripts/build.sh

4. Verify installation:

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

5. Create and launch a VM:

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

Summary

• Hardware: Requires physical Apple Silicon (ARM64); Intel Macs and nested virtualization are unsupported.
• OS: macOS 15 (Sequoia) minimum for Virtualization.framework v2 and PV=3 APIs.
• Security: Must relax SIP/AMFI or use vphone-amfidont to allow private entitlements.
• Tools: Xcode, iOS SDK, and specific Homebrew packages (python@3.13, ldid-procursus, etc.).
• Build: Execute scripts/setup_tools.sh and scripts/build.sh (or make build) to handle Python venv creation and Swift compilation.

Frequently Asked Questions

Can I run vphone-cli on an Intel Mac?

No. According to the source code in sources/vphone-cli/VPhoneVirtualMachine.swift, the tool depends on PV=3 private virtualization entitlements that are exclusively available on Apple Silicon ARM64 architecture. Intel Macs lack the necessary hardware virtualization extensions for this specific iOS virtualization mode.

Why does vphone-cli require disabling SIP?

Private Virtualization (PV=3) uses undocumented Apple Virtualization.framework APIs that require elevated privileges and unsigned code execution. The vphone-cli binary must load these private symbols dynamically, which macOS's AMFI (Apple Mobile File Integrity) blocks by default. Disabling SIP or using vphone-amfidont permits this research-level access.

What happens if I run vphone-cli on macOS 14 or earlier?

The application will fail to initialize the virtual machine. The code specifically requires Virtualization.framework v2 introduced in macOS 15 (Sequoia) to handle PV=3 configurations. Earlier OS versions lack the API surface necessary to create the VZVirtualMachineConfiguration with private entitlement flags.

Do I need an Apple Developer account to build vphone-cli?

No paid Developer account is required for local builds. The scripts/build.sh uses ad-hoc code signing suitable for research purposes on SIP-disabled systems. However, you must have Xcode installed (available free from the Mac App Store) to access the iOS SDK for cross-compiling the vphoned guest daemon.

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