Booting a Virtual iPhone via Apple's Virtualization.framework

This project, known as vphone-cli, enables the execution of a virtualized iPhone environment by leveraging Apple's Virtualization.framework and the PCC research VM infrastructure.

---

🛠 Prerequisites

To successfully run this environment, your host machine must meet the following criteria:

• Hardware: Apple Silicon (M-series).
• OS: macOS 15+ (Sequoia).
• Tooling: Xcode and the iOS SDK (required for cross-compiling the guest daemon).
• Security: Relaxation of SIP (System Integrity Protection) and AMFI (Apple Mobile File Integrity) to permit private PV=3 entitlements for unsigned binaries.

Required Dependencies

Install the following via Homebrew: brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

---

🚀 Installation

Option 1: Rapid Install

The fastest way to get started is via the tap:

brew install zqxwce/tap/vphone-cli

Option 2: Manual Build

If you prefer building from source, follow these steps:

• Clone the repository with submodules: git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
• Initialize the environment: ./scripts/setup_tools.sh (Installs dependencies, builds toolchains, and sets up the Python venv)
• Compile the project: ./scripts/build.sh (Builds/signs the CLI, bundles the .app, and cross-compiles vphoned)

To verify the installation:

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

---

📱 Quick Start & Workflow

You can deploy a VM in a single step, which handles everything from downloading the firmware to the initial boot.

The "One-Shot" Command: vphone-cli vm create myphone -V jb $\rightarrow$ vphone-cli vm launch myphone (Note: -V or --variant specifies the patch level)

The VM Lifecycle Pipeline

The vm create command is essentially a wrapper for the following sequence:

Manual Pipeline $\rightarrow$ Automated Pipeline (via vm create)

---

⌨️ Command Reference

VM Management

Manual Build Steps

If you need granular control, execute these in order:

1. vphone-cli vm new myphone
2. vphone-cli fw prepare myphone --iphone-version 26.1 (Downloads/merges IPSWs)
3. vphone-cli fw patch myphone --variant jb (Patches for boot)
4. vphone-cli restore myphone --get-shsh $\rightarrow$ vphone-cli restore myphone (DFU restore)
5. vphone-cli vm stop myphone (Exit DFU mode)
6. vphone-cli cfw install myphone --variant jb (Installs Custom Firmware via sudo)
7. vphone-cli vm launch myphone

Pro Tip: To update iOS, run fw prepare again and point to specific files using --iphone-source /path/to.ipsw and --cloudos-source /path/to.ipsw.

---

🛠 Firmware Variants

The --variant flag determines the level of security bypasses applied.

Detailed breakdowns are available in research/0_binary_patch_comparison.md.

---

🔌 Connectivity & Access

Once the VM is running, you can connect via the following methods:

• SSH (Jailbroken): ssh -p 22222 mobile@<vm-ip> (Password: alpine)
• SSH (Dev/Regular): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

---

📂 File System & Storage

All data is stored in ~/.vphone/ to keep the signed .app bundle portable.

Path Hierarchy:

• $VPHONE_ROOT (Default: ~/.vphone/): The primary data directory.
• .../ipsws/: Cached iPhone and cloudOS firmware.
• .../tools/: APFS seal-volume artifacts (apfs_sealvolume_).
• .../debs/: Cached packages for jb/exp variants (e.g., apt).
• .../venv/: The Python runtime environment (Override via $VPHONE_VENV_DIR).

Priority Logic: $\text{Override Variable} \rightarrow \$VPHONE\_ROOT \rightarrow \text{Default } \sim/.vphone$

---

🔐 SIP/AMFI Relaxation

You must choose one of two paths to allow the binary to run:

Option A: Maximum Permissiveness

1. Boot into Recovery $\rightarrow$ Terminal.
2. Run: csrutil disable and csrutil allow-research-guests enable.
3. Reboot and set the AMFI boot-arg: sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

Option B: Targeted Relaxation

1. Boot into Recovery $\rightarrow$ Terminal.
2. Run: csrutil enable --without debug and csrutil allow-research-guests enable.
3. Reboot and run the allowlist tool: vphone-amfidont (Found in .build/vphone-cli.app/Contents/Resources/)

---

🧪 Compatibility Matrix