How to Build vphone-cli from Source on macOS

To build vphone-cli from source, clone the repository with submodules, install Homebrew dependencies (Python 3.13, ldid-procursus, etc.), run make setup_tools to prepare the toolchain, then execute make build to compile the Swift binary and sign it with private entitlements.

vphone-cli is a pure-Swift macOS tool that boots a virtual iPhone using Apple's Virtualization.framework (PV=3). Because the project relies on private APIs and a cross-compiled guest daemon, building from source requires specific dependencies and entitlements. This guide walks through the exact steps defined in the Makefile at the root of the Lakr233/vphone-cli repository.

Prerequisites

Building vphone-cli requires specific hardware and software:

• An Apple Silicon Mac (Intel Macs are not supported)
• macOS 15 (Sequoia) or later (PV=3 virtualization is unavailable on earlier versions)
• Homebrew installed for dependency management

Step-by-Step Build Instructions

1. Clone the Repository Including Submodules

The project includes submodules for the toolchain. Clone with the --recurse-submodules flag to fetch all required dependencies:

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

2. Install Host-Side Dependencies

Install the required Homebrew packages. These include Python 3.13, cryptographic tools, and utilities for iOS development:

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

3. Run the Tool Setup Script

The setup_tools target (defined in Makefile at lines 70-73) invokes scripts/setup_tools.sh to build the Python virtual environment and compile helper binaries:

make setup_tools

This script creates .venv, builds sub-modules (trustcache, insert_dylib, libimobiledevice), and populates ./.tools/ with the compiled helper binaries required for patching firmware images.

4. Compile the Swift Binary

The make build target compiles the release binary and applies private entitlements. According to the Makefile (lines 7-22), this process first runs:

swift build -c release

Then signs the resulting binary with the private API entitlements from sources/vphone.entitlements:

codesign --force --sign - --entitlements sources/vphone.entitlements .build/release/vphone-cli

To execute the complete build sequence, simply run:

make build

The signed executable appears at .build/release/vphone-cli.

5. Bundle into macOS App Format (Optional)

To create a .app bundle instead of a raw binary, use the bundle target defined in Makefile lines 27-36:

make bundle

This assembles .build/vphone-cli.app containing the signed binary, Info.plist, the application icon, and the ldid binary.

6. Build the Guest Daemon (Optional)

For full VM functionality, you must build vphoned (the iOS-side control daemon). The Makefile target at lines 38-50 cross-compiles the Objective-C source in scripts/vphoned/ for arm64 and signs it with ldid:

make vphoned

This creates a signed vphoned binary and places it inside the VM directory at $(VM_DIR)/.vphoned.signed.

Verification and Troubleshooting

Test that the build succeeded by requesting help output:

.build/release/vphone-cli --help

If the binary fails to launch due to AMFI (Apple Mobile File Integrity) or SIP (System Integrity Protection) violations, run the preflight check:

make boot_host_preflight

This diagnostic tool surfaces entitlement issues. For resolution, refer to the "SIP/AMFI Relaxation" section in README.md, which explains how to allow the private com.apple.vm.private-manager entitlement required by sources/vphone.entitlements.

Summary

• Hardware requirement: Apple Silicon Mac with macOS 15+ is mandatory due to PV=3 virtualization dependencies.
• Build orchestration: The Makefile provides atomic targets (setup_tools, build, bundle, vphoned) that handle the complex cross-compilation and signing workflow.
• Entitlements: The binary must be signed with sources/vphone.entitlements to access Virtualization.framework's private interfaces.
• Guest components: The vphoned daemon requires separate compilation via make vphoned to enable full iOS VM control inside the virtualized environment.

Frequently Asked Questions

Can I build vphone-cli on an Intel Mac?

No. The tool uses Virtualization.framework with PV=3 (platform virtualization version 3), which is only supported on Apple Silicon (ARM64) Macs. The private APIs referenced in sources/vphone.entitlements are unavailable on x86_64 architecture, and the project will fail to compile or run on Intel hardware.

Why does the build require Python 3.13 and ldid-procursus?

The build process relies on Python scripts to parse and patch IPSW firmware images, while ldid (from the Procursus team) is required to ad-hoc sign the guest daemon vphoned for iOS arm64 execution inside the virtual machine. The make setup_tools target executes scripts/setup_tools.sh to automatically build these dependencies and create the Python virtual environment at .venv.

What are the private entitlements for?

The sources/vphone.entitlements file contains the com.apple.vm.private-manager entitlement necessary to invoke Virtualization.framework's private PV=3 interfaces. Without these entitlements—applied during the codesign step in the Makefile—the binary cannot instantiate the virtual iPhone device even if compilation succeeds.

How do I verify the build succeeded without running a full VM?

Execute .build/release/vphone-cli --help to confirm the binary launches without code signing errors. If you encounter "AMFI: code signature validation failed" messages, run make boot_host_preflight to diagnose SIP/entitlement misconfigurations before attempting to boot a virtual device.

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