System Requirements for vphone-cli: Hardware, Software, and Security Prerequisites

vphone-cli requires an Apple Silicon Mac running macOS 15 (Sequoia) or later, with System Integrity Protection (SIP) and AMFI relaxed or disabled to allow private Virtualization.framework entitlements.

vphone-cli is a macOS-only utility that boots virtual iPhone instances using Apple’s Virtualization.framework. To run this tool from the Lakr233/vphone-cli repository, your host system must meet strict hardware, software, and security prerequisites due to its reliance on private APIs and low-level virtualization features.

Hardware Prerequisites

The tool exclusively supports Apple Silicon (ARM64) Macs. According to the implementation in sources/vphone-cli/VPhoneVirtualMachine.swift, the Virtualization.framework requires PV = 3 (Platform Version 3), which is only available on Apple Silicon processors. Intel-based Macs cannot instantiate the virtual machine configuration, and attempting to run the binary on x86_64 architecture will fail during the VZVirtualMachineConfiguration setup.

Operating System and Developer Tools

You must run macOS 15 (Sequoia) or later. This version ships with Virtualization.framework version 5, which provides the necessary APIs for the guest VM lifecycle. Additionally, you need Xcode and the iOS SDK installed to cross-compile the guest daemon (vphoned) and to link against the private frameworks required for VM orchestration.

Security Configuration: SIP and AMFI Relaxation

This is the most critical non-negotiable requirement. The VM requires private entitlements that are blocked by macOS security mechanisms. You have two approaches to satisfy this:

• Full Relaxation: Disable System Integrity Protection (SIP) and set the boot argument amfi_get_out_of_my_way=1.
• Allow-List Approach: Use the "amfidont" method to selectively allow the specific binary without fully disabling SIP.

Without one of these configurations, the host kernel will refuse to grant the necessary entitlements to the unsigned binary, and VPhoneControl.swift will fail to establish the vsock connection to the in-VM daemon.

Package Dependencies and Installation

The scripts/setup_tools.sh script automates the installation of required Homebrew packages. Ensure you have the following dependencies present before running the setup:

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

These packages provide the Python 3.13 runtime, networking tools (aria2, wget), cryptographic utilities (openssl@3), and the ldid-procursus binary used for ad-hoc code signing of the patched firmware. The script also creates an isolated Python virtual environment at .venv/ within the project directory to run the firmware preparation scripts.

Runtime Environment and Directory Structure

By default, vphone-cli stores all mutable data—including VM bundles, downloaded IPSW files, cached tools, and the Python virtual environment—in ~/.vphone/. You can override this location by setting the $VPHONE_ROOT environment variable. The signed .app bundle generated by the tool remains portable, but all heavy assets reside in this user data directory.

The scripts/fw_prepare.sh script manages the download and caching of IPSW files under ~/.vphone/ipsws/, handling the merge of iPhone and CloudOS images required for the virtualized boot chain.

Core Implementation Files

Understanding the system requirements is easier when referencing the specific source files that enforce them:

• sources/vphone-cli/main.swift: The entry point that initializes NSApplication and parses CLI arguments before delegating to the VM controller.
• sources/vphone-cli/VPhoneVirtualMachine.swift: Configures the VZVirtualMachineConfiguration and enforces the Apple Silicon/PV=3 platform requirement.
• sources/vphone-cli/VPhoneControl.swift: Implements the host-side vsock client that communicates with the vphoned daemon running inside the guest VM.
• scripts/setup_tools.sh: Installs Homebrew dependencies, builds submodules, and constructs the Python virtual environment.
• scripts/fw_prepare.sh: Automates IPSW downloads and custom firmware (CFW) image preparation, storing artifacts in the user data directory.

Quick Start Verification

Once you have satisfied the hardware, OS, and security requirements, verify your installation with these commands:

# Install the pre-built Homebrew formula (includes the binary)

brew install zqxwce/tap/vphone-cli

# Create a new VM with the jailbreak variant

vphone-cli vm create myphone -V jb

# Launch the VM

vphone-cli vm launch myphone

# Connect via SSH (regular/dev VM)

ssh -p 22222 root@$(vphone-cli vm info myphone --json | jq -r .ip)

# Install an IPA into the running VM

vphone-cli vm install myphone MyApp.ipa

These commands exercise the full stack: the Swift CLI in main.swift, the VM lifecycle management in VPhoneVirtualMachine.swift, and the Python-based firmware patching pipeline invoked during the vm create phase.

Summary

• Hardware: Apple Silicon (ARM64) is mandatory; Intel Macs are incompatible.
• Operating System: macOS 15 (Sequoia) or later is required for Virtualization.framework v5.
• Security: SIP and AMFI must be relaxed via boot arguments or the "amfidont" allow-list to grant private entitlements.
• Dependencies: Install specific Homebrew packages including python@3.13, ldid-procursus, and keystone before running scripts/setup_tools.sh.
• Storage: Ensure sufficient space in ~/.vphone/ (or $VPHONE_ROOT) for IPSWs and VM bundles.
• Development: Xcode and iOS SDK are needed to compile the guest daemon and link private frameworks.

Frequently Asked Questions

Can I run vphone-cli on an Intel Mac?

No. According to the implementation in sources/vphone-cli/VPhoneVirtualMachine.swift, the tool requires Virtualization.framework PV = 3, which only supports Apple Silicon (ARM64) hosts. The VZVirtualMachineConfiguration initialization will fail on Intel architecture.

Why does vphone-cli require disabling SIP?

The tool utilizes private entitlements to access low-level virtualization features and mount the custom firmware (CFW) image. System Integrity Protection (SIP) and AMFI block these entitlements for unsigned binaries. You must either fully disable SIP with amfi_get_out_of_my_way=1 or use the "amfidont" allow-list approach documented in the repository README.

What is stored in the ~/.vphone/ directory?

This directory (or the path specified by $VPHONE_ROOT) contains all non-portable data: downloaded IPSW firmware files, cached tools, Python virtual environments (.venv/), and the VM bundle images created by vphone-cli vm create. The signed .app bundles themselves are portable, but their backing data resides here.

Do I need a physical iPhone to use vphone-cli?

No. The tool downloads and patches official IPSW firmware files to create a fully virtualized iPhone environment. As implemented in scripts/fw_prepare.sh, it automatically retrieves the necessary firmware images from Apple's servers and merges them with CloudOS components, requiring only the host Mac to meet the system requirements outlined above.

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