# Prerequisites for Running vphone-cli on Apple Silicon: Complete Setup Guide

> Set up vphone-cli on Apple Silicon with macOS 15+, Xcode, Homebrew, and adjusted security settings. Get the complete guide to running vphone-cli.

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

---

**To run vphone-cli on Apple Silicon, you need an ARM-based Mac running macOS 15 (Sequoia) or later, Xcode with iOS SDK, specific Homebrew dependencies, and relaxed SIP/AMFI security settings to allow private Virtualization.framework entitlements.**

The `Lakr233/vphone-cli` project is a macOS-specific tool that boots a virtual iPhone using Apple's **Virtualization.framework** with **PV=3** (private virtualization) entitlements. Meeting these prerequisites for running vphone-cli on Apple Silicon ensures the host can execute the unsigned binary and manage iOS guest VMs through private APIs that are exclusive to ARM-based hardware.

## Hardware and Operating System Requirements

### Apple Silicon Mac (ARM64)

vphone-cli requires a **genuine Apple Silicon Mac** (M1, M2, M3, or later). The tool leverages **PV=3** entitlements that are exclusively available on physical ARM-based Apple Silicon hardware. According to the source code in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), this virtualization mode cannot be nested inside another virtual machine, making bare-metal Apple Silicon mandatory.

### macOS Sequoia 15 or Later

You must run **macOS 15 (Sequoia)** or newer. The project depends on **Virtualization.framework v2**, which introduced support for PV=3 APIs specifically in macOS 15. Earlier macOS releases lack the necessary private frameworks to instantiate the virtual iPhone hardware configuration.

## Security and Entitlement Prerequisites

### Private Virtualization (PV=3) Access

As implemented in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), the Swift code uses the **Dynamic** library to call private Virtualization.framework APIs at runtime. This avoids compile-time linking against restricted symbols, but still requires the host system to permit unsigned code with research entitlements.

### SIP and AMFI Relaxation Options

Because PV=3 entitlements are private and undocumented, the `vphone-cli` binary must run with signatures that macOS typically blocks. The repository provides two approaches in the documentation:

**Option A: Disable SIP and AMFI**
Fully disable System Integrity Protection (SIP) and set the `amfi_get_out_of_my_way=1` boot argument:

```bash
csrutil disable && csrutil allow-research-guests enable
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

```

**Option B: Use vphone-amfidont with SIP Enabled**
Keep SIP partially enabled while whitelisting the binary using the provided helper:

```bash
csrutil enable --without debug
csrutil allow-research-guests enable
vphone-amfidont  # Provided in the app bundle

```

## Development Tools and Dependencies

### Xcode and iOS SDK

You need **Xcode** installed with the **iOS SDK**. The build process in [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) cross-compiles the guest daemon `vphoned` for iOS architecture during the host build pipeline. Without Xcode's toolchain, the Swift compiler cannot generate the universal binaries required for the virtual iPhone environment.

### Required Homebrew Packages

The Python-based patcher and supporting toolchain require several command-line utilities. Install them via Homebrew:

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

```

These tools handle IPSW downloading, binary patching (`ldid-procursus`), and firmware extraction.

## Build Environment Configuration

### Python Virtual Environment Setup

The [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) script creates a dedicated Python virtual environment (`.venv`) installing specific packages required for binary manipulation:

- `capstone`
- `keystone-engine`
- `pyimg4`

Run [`./scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/./scripts/setup_tools.sh) to initialize this environment before building.

### Swift Build and Code Signing

The [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) script compiles the Swift binary, applies ad-hoc code signatures, and cross-compiles the iOS guest daemon. The resulting executable resides at `.build/vphone-cli.app/Contents/MacOS/vphone-cli`. The build process referenced in the repository's **Makefile** (`make build`) orchestrates these steps automatically.

## Step-by-Step Installation

Follow this sequence to satisfy all prerequisites and build the project:

1. **Install dependencies** and ensure macOS 15+ is active:

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

2. **Configure security settings** (choose Option A or B from above). For development, Option A is typically used:

   ```bash
   csrutil disable
   csrutil allow-research-guests enable
   sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
   ```

3. **Clone and build** the repository:

   ```bash
   git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
   cd vphone-cli
   ./scripts/setup_tools.sh
   ./scripts/build.sh
   ```

4. **Verify installation**:

   ```bash
   cd .build/vphone-cli.app/Contents/MacOS/
   ./vphone-cli --help
   ```

5. **Create and launch a VM**:

   ```bash
   ./vphone-cli vm create myphone -V jb
   ./vphone-cli vm launch myphone
   ```

## Summary

- **Hardware**: Requires physical Apple Silicon (ARM64); Intel Macs and nested virtualization are unsupported.
- **OS**: macOS 15 (Sequoia) minimum for Virtualization.framework v2 and PV=3 APIs.
- **Security**: Must relax SIP/AMFI or use `vphone-amfidont` to allow private entitlements.
- **Tools**: Xcode, iOS SDK, and specific Homebrew packages (`python@3.13`, `ldid-procursus`, etc.).
- **Build**: Execute [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) and [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) (or `make build`) to handle Python venv creation and Swift compilation.

## Frequently Asked Questions

### Can I run vphone-cli on an Intel Mac?

No. According to the source code in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), the tool depends on **PV=3** private virtualization entitlements that are exclusively available on Apple Silicon ARM64 architecture. Intel Macs lack the necessary hardware virtualization extensions for this specific iOS virtualization mode.

### Why does vphone-cli require disabling SIP?

Private Virtualization (PV=3) uses undocumented Apple Virtualization.framework APIs that require elevated privileges and unsigned code execution. The `vphone-cli` binary must load these private symbols dynamically, which macOS's AMFI (Apple Mobile File Integrity) blocks by default. Disabling SIP or using `vphone-amfidont` permits this research-level access.

### What happens if I run vphone-cli on macOS 14 or earlier?

The application will fail to initialize the virtual machine. The code specifically requires **Virtualization.framework v2** introduced in macOS 15 (Sequoia) to handle PV=3 configurations. Earlier OS versions lack the API surface necessary to create the `VZVirtualMachineConfiguration` with private entitlement flags.

### Do I need an Apple Developer account to build vphone-cli?

No paid Developer account is required for local builds. The [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) uses ad-hoc code signing suitable for research purposes on SIP-disabled systems. However, you must have Xcode installed (available free from the Mac App Store) to access the iOS SDK for cross-compiling the `vphoned` guest daemon.