# vphone-cli Requirements for Apple Silicon: Complete Setup Guide

> Learn vphone-cli requirements for Apple Silicon. Discover necessary macOS, hardware, Xcode, and Python setup for this powerful CLI tool.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: getting-started
- Published: 2026-09-06

---

**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](https://github.com/Lakr233/vphone-cli) project by [Lakr233](https://github.com/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) file declares strict toolchain requirements:

```swift
// 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`](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt) specifies binary analysis dependencies for firmware patching:

```text
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:

```bash

# 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:

```ini
[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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/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.