vphone-cli Requirements for Apple Silicon: Complete Setup Guide

vphone-cli requires macOS 15+, Apple Silicon hardware with SIP and AMFI disabled, Xcode 16 with Swift 6.0, and a configured Python environment with binary analysis libraries.

The vphone-cli project by Lakr233 is a macOS-exclusive command-line tool that virtualizes iOS devices using Apple's Virtualization.framework with private PV=3 APIs. Running it on Apple Silicon demands specific hardware configurations, disabled security protections, and a multi-language build environment. This guide breaks down every requirement with source-level accuracy.

macOS Version and Hardware Requirements

Operating System: macOS 15 Sequoia or Later

vphone-cli depends on Virtualization.framework features introduced in macOS 15. According to AGENTS.md, the platform support table explicitly lists:

Platform	Variants
macOS 15+	1, 2, 3, UNKNOWN

The PV=3 virtualization mode required for virtualized iPhone boot is only available starting with macOS 15. Earlier macOS versions lack the necessary private framework extensions.

Hardware: Apple Silicon Mandatory

The tool is architecturally bound to Apple Silicon (M1/M2/M3/…). Intel Macs are unsupported because:

• Virtualization.framework's PV=3 mode requires ARM-based CPU virtualization extensions
• The kernel patching mechanisms target arm64-specific memory layouts
• Firmware scripts assume arm64 binary formats

Critical Security Requirements: Disabled SIP and AMFI

System Integrity Protection (SIP)

vphone-cli requires complete SIP disablement to load private entitlements and kernel-level components. The scripts/setup_machine.sh file contains environment preparation logic, and repository documentation notes that standard SIP-blocked systems reject the tool's code signature modifications.

Apple Mobile File Integrity (AMFI)

AMFI must also be disabled via boot arguments. The private APIs used for virtualized device management trigger AMFI enforcement failures when active. Users must boot into Recovery Mode and execute:

# From Recovery Mode terminal

csrutil disable

# Additional AMFI boot argument required

nvram boot-args="amfi_get_out_of_my_way=1"

These security downgrades are documented as non-optional in the project's architecture overview.

Development Toolchain Requirements

Xcode 16 and Swift 6.0

The Package.swift file declares strict toolchain requirements:

// swift-tools-version:5.10
// When opened in Xcode, this package requires Swift 6.0

import PackageDescription

let package = Package(
    name: "vphone",
    platforms: [.macOS(.v14)],
    // ...
)

Building requires:

• Xcode 16 or later installed
• Swift 6.0 toolchain active
• Command-line tools: xcode-select --install

Swift Package Dependencies

The project pulls in Dynamic via submodule at scripts/repos/Dynamic/—a Swift package enabling runtime method dispatch without Objective-C bridging, essential for calling private Virtualization.framework APIs.

Python Environment and Firmware Tools

Required Python Packages

The requirements.txt specifies binary analysis dependencies for firmware patching:

capstone
keystone-engine
pyimg4

These power the patcher scripts in scripts/patchers/ for:

• capstone: Disassembling arm64 kernel binaries
• keystone-engine: Re-assembling modified instructions
• pyimg4: Parsing and resigning IMG4 firmware containers

Virtual Environment Setup

The Makefile automates Python environment preparation:

# From repository root

make setup_venv

This creates an isolated Python 3 environment with all cryptographic and binary analysis tools. The Makefile targets include:

Target	Purpose
setup_venv	Creates Python venv and installs requirements
build	Compiles Swift executable with release optimizations
boot	Launches virtualized iPhone with GUI attachment

External Dependencies and Submodules

Git Submodules

The .gitmodules file tracks three critical external projects:

[submodule "scripts/repos/trustcache"]
    path = scripts/repos/trustcache
    url = https://github.com/CRKatri/trustcache
[submodule "scripts/repos/insert_dylib"]
    path = scripts/repos/insert_dylib
    url = https://github.com/Tyilo/insert_dylib
[submodule "scripts/repos/libimobiledevice"]
    path = scripts/repos/libimobiledevice
    url = https://github.com/libimobiledevice/libimobiledevice

These provide:

• trustcache: Custom trust cache manipulation for bypassing code signing
• insert_dylib: Dynamic library injection for patched binaries
• libimobiledevice: USB communication with virtualized iOS devices

Clone with --recurse-submodules or run git submodule update --init --recursive after standard clone.

Host-Side Installation Privileges

The scripts/cfw_install_host.sh script requires sudo access for:

• Mounting disk images containing kernel extensions
• Installing CFW (Custom Firmware) drivers
• Manipulating virtualization storage backends

Complete Installation Workflow

Execute these commands in sequence on a prepared Apple Silicon Mac:

# 1. Verify macOS version (must report 15.0 or higher)

sw_vers -productVersion

# 2. Install Xcode 16 and select it

sudo xcode-select -s /Applications/Xcode.app

# 3. Clone with all submodules

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

# 4. Build the Swift executable

make build

# 5. Prepare Python environment for firmware operations

make setup_venv

# 6. Verify installation

./.build/release/vphone --help

Verification Checklist

Before attempting to boot a virtual device, confirm:

• macOS 15+ running on Apple Silicon
• SIP disabled (csrutil status reports disabled)
• AMFI disabled (boot-args contain amfi_get_out_of_my_way=1)
• Xcode 16 with Swift 6.0 selected
• Git submodules populated (ls scripts/repos/ shows all three directories)
• Python venv active and packages installed
• Sudo access available for CFW installation steps

Summary

• vphone-cli requires macOS 15+ on Apple Silicon with SIP and AMFI completely disabled to function
• Build dependencies include Xcode 16, Swift 6.0, and the Dynamic Swift package for private API access
• Runtime firmware manipulation depends on Python 3 with capstone, keystone-engine, and pyimg4 in an isolated virtual environment
• External C tools from trustcache, insert_dylib, and libimobiledevice submodules enable complete virtualized iOS device lifecycle management
• Administrative privileges via sudo are required for host-side driver installation and disk manipulation

Frequently Asked Questions

Can vphone-cli run on Intel Macs with macOS 15?

No. The tool is architecturally restricted to Apple Silicon. The Virtualization.framework PV=3 mode and arm64-specific kernel patching mechanisms in scripts/patchers/ explicitly target ARM64 CPU features unavailable on Intel hardware.

Is disabling SIP and AMFI safe for daily use?

Disabling these security features exposes your system to elevated risk. The repository documentation treats this as a development/ research configuration only. Consider dedicated hardware or virtualized macOS environments for vphone-cli experimentation rather than daily-driver machines.

Why does the build fail with "no such module 'Virtualization'"?

This indicates macOS 14 or earlier, or SIP/AMFI partially enabled. The private Virtualization.framework headers required by Package.swift are only accessible when system protections are fully disabled and macOS 15+ is active. Verify with sw_vers and csrutil status.

Can I use an existing Python installation instead of make setup_venv?

Technically possible, but discouraged. The Makefile creates an isolated environment to prevent conflicts with system Python packages. The firmware patchers depend on specific capstone and keystone-engine versions that may conflict with other installed tools.

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