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

> Discover vphone-cli system requirements. Ensure your Apple Silicon Mac runs macOS 15+, with SIP and AMFI configured for private Virtualization.framework entitlements. Get vphone-cli running smoothly.

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

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) will fail to establish the vsock connection to the in-VM daemon.

## Package Dependencies and Installation

The [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) script automates the installation of required Homebrew packages. Ensure you have the following dependencies present before running the setup:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift)**: Configures the `VZVirtualMachineConfiguration` and enforces the Apple Silicon/PV=3 platform requirement.
- **[`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh)**: Installs Homebrew dependencies, builds submodules, and constructs the Python virtual environment.
- **[`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/main.swift), the VM lifecycle management in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.