# How to Build vphone-cli from Source on macOS

> Learn to build vphone-cli from source on macOS. Clone the repo, install dependencies, and compile the Swift binary for your project.

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

---

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

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

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) to build the Python virtual environment and compile helper binaries:

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

```bash
swift build -c release

```

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

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

```

To execute the complete build sequence, simply run:

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

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

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

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

```bash
make boot_host_preflight

```

This diagnostic tool surfaces entitlement issues. For resolution, refer to the "SIP/AMFI Relaxation" section in [`README.md`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.