How to Install vphone-cli on Apple Silicon: Homebrew and Build-from-Source Guide

You can install vphone-cli on macOS 15 Sequoia or later using Homebrew (brew install zqxwce/tap/vphone-cli) or by cloning the Lakr233/vphone-cli repository, running scripts/setup_tools.sh, and executing scripts/build.sh to produce a signed binary at .build/vphone-cli.app/Contents/MacOS/vphone-cli.

vphone-cli is a Swift 6.0 command-line tool that leverages Apple’s Virtualization.framework to boot virtual iPhones on Apple Silicon Macs. The repository provides both a pre-built Homebrew formula and a complete build pipeline for local compilation. This guide covers both installation methods, the mandatory system prerequisites, and how to verify your setup before creating your first VM.

Prerequisites for Installing vphone-cli

Before installing vphone-cli, ensure your host system meets the strict hardware and software requirements enforced by the Virtualization.framework and the tool’s jailbreak components.

Hardware and Software Requirements

vphone-cli requires Apple Silicon (M-series chips) and cannot run on Intel Macs. You must have macOS 15 Sequoia or later installed, along with the full Xcode application—not just the command-line tools—to access the iOS SDK required for cross-compiling the guest daemon. The virtualization stack relies on specific entitlements and frameworks only available on Apple Silicon running macOS 15+.

SIP and AMFI Configuration

System Integrity Protection (SIP) and AMFI must be relaxed to allow the virtual machine’s boot chain patching and trust cache injection. According to the Lakr233/vphone-cli source documentation, these security relaxations are mandatory for the binary to function correctly whether you use the Homebrew distribution or build from source. Refer to the repository’s README for the exact csrutil and boot-args commands required before proceeding with installation.

Install vphone-cli via Homebrew (Recommended)

The fastest way to install vphone-cli uses the third-party Homebrew tap maintained by the project. This method downloads the latest pre-built, signed binary and installs the vphone-cli command into your PATH without requiring local compilation.

Run the following command in Terminal:

brew install zqxwce/tap/vphone-cli

Homebrew handles the entitlements and code signing automatically, placing the executable in your environment. After installation completes, proceed to the verification step to confirm the binary is accessible.

Build vphone-cli from Source

If you need to modify the source code in sources/vphone-cli/main.swift or debug the VPhoneVirtualMachine.swift configuration logic, building locally provides full control over the compilation process.

Clone the Repository

First, clone the repository including all necessary submodules:

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

The --recurse-submodules flag is critical as the project depends on external components for the guest daemon and virtualization helpers.

Run Setup Scripts

Prepare the build environment by executing the setup script, which installs runtime dependencies including trustcache, insert_dylib, and configures the Python virtual environment:

./scripts/setup_tools.sh

This script automates the installation of tools required by the build pipeline and guest environment preparation.

Build the Application Bundle

Compile the Swift executable and generate the signed .app bundle using the build script:

./scripts/build.sh

The script compiles sources/vphone-cli/VPhoneCLI.swift (which implements the ArgumentParser-based command interface) along with VPhoneAppDelegate.swift and VPhoneControl.swift to produce the final binary. Upon completion, the signed executable resides at:

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

You can either run the binary directly from this path or symlink it to a directory in your PATH for global access.

Verify Your Installation

Regardless of installation method, confirm that vphone-cli is correctly installed and accessible by invoking the help command:

vphone-cli --help

You should see the command-line interface options including the vm create and vm launch commands implemented in VPhoneCLI.swift. Successful output indicates that the binary, entitlements, and Virtualization.framework dependencies are properly configured.

Next Steps: Creating Your First Virtual iPhone

Once installation is verified, initialize your first virtual machine using the jailbreak variant:

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

These commands trigger the full provisioning pipeline: downloading IPSWs, patching the boot chain, performing a DFU restore, installing the custom firmware, and booting the virtualized iOS environment through the VZVirtualMachineConfiguration defined in the source.

Summary

• vphone-cli requires Apple Silicon running macOS 15+ with Xcode and SIP/AMFI relaxation
• Homebrew installation uses brew install zqxwce/tap/vphone-cli for immediate deployment
• Source builds require cloning with submodules, running scripts/setup_tools.sh, then scripts/build.sh
• The compiled binary outputs to .build/vphone-cli.app/Contents/MacOS/vphone-cli
• Key source files include main.swift, VPhoneVirtualMachine.swift, and VPhoneCLI.swift
• Verify installation with vphone-cli --help before creating VMs

Frequently Asked Questions

Can I install vphone-cli on Intel Macs?

No, vphone-cli is exclusively compatible with Apple Silicon (M1, M2, M3, and later). The tool relies on Apple’s Virtualization.framework and specific CPU virtualization features only present in M-series chips. Attempting to build or run the tool on Intel architectures will fail during compilation or runtime.

Why do I need to disable SIP and AMFI?

The virtualization process requires modifying system-level trust caches and injecting dynamic libraries into the virtualized iOS kernel, operations that macOS security frameworks normally block. Disabling SIP (System Integrity Protection) and relaxing AMFI (Apple Mobile File Integrity) allows vphone-cli to patch the secure boot chain and manage the VM’s hardware virtualization layer as implemented in VPhoneVirtualMachine.swift.

Where is the vphone-cli binary located when building from source?

When compiling manually, the signed executable is placed at .build/vphone-cli.app/Contents/MacOS/vphone-cli relative to the repository root. This path contains the Swift 6.0 binary built by scripts/build.sh along with necessary entitlements and bundle resources required for Virtualization.framework access.

How do I update vphone-cli to the latest version?

If installed via Homebrew, run brew upgrade zqxwce/tap/vphone-cli to fetch the latest pre-built release. For source installations, pull the latest changes with git pull --recurse-submodules and re-run scripts/build.sh to recompile the binary with the updated source from sources/vphone-cli/.

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