v2.0.4

vphone-cli 2.0.4

Version 2 brings the firmware, restore, and virtual machine tools into a self-contained VPhone.bundle. Version 2.0.4 ships a notarized vphone-launchpad Mac app that installs the bundle and guides you from host setup to a running virtual iPhone. This note covers the changes since 1.0.14.

Get Started

Use a physical Apple Silicon Mac running macOS 15 or newer.

1. In macOS Recovery, run csrutil enable --without debug and csrutil allow-research-guests enable, then restart. SIP remains enabled with debugging restrictions relaxed. See host setup for details.
2. Download the notarized vphone-launchpad 2.0.4, unzip it, and open the app. Follow Host Setup to grant Developer Tools access and install its helper.
3. In Core Bundle, choose Download and Install. Launchpad downloads and verifies VPhone.bundle, then checks that its VM executable can run on this Mac.
4. In Machines, choose New Machine, select a firmware pair, and choose Create. Launchpad prepares the firmware, restores the VM, installs the guest changes, and checks the first boot. The VM stays running when creation succeeds.

Creation requires network access and substantial free disk space. You can also provide compatible local iPhone and cloudOS IPSWs. See the tested firmware pairs.

In 2.0.4, firmware preparation stops with a clear error when the iPhone and cloudOS IPSWs are swapped or do not match the selected roles. Launchpad also shows the creation log in its own sheet so you can follow each stage or inspect a failure.

What Changed Since 1.x

One Complete Firmware Configuration

Version 2 applies the complete firmware patch set, including changes previously offered as EXP. There are currently no patch variants to choose from. Keeping one configuration gives firmware preparation, restore, and first boot the same path to validate and diagnose. Every new VM includes vphoned and the system changes needed for host control. A package manager is not installed by default; Guest > Install Bootstrap… is a separate, optional step after the VM starts.

A Self-Contained Runtime

The release bundle contains the CLI, VM process, firmware patcher, native restore backend, and guest components. The distributed runtime needs no Xcode, Python, or Homebrew installation. Firmware preparation and restore use the project's native Swift and C code, so the release can validate the components it ships instead of depending on a separately configured interpreter and tools. Guest system changes are installed through a host-mounted volume during creation, without requiring an SSH service in the guest.

vphone-cli remains available for terminal workflows. It handles preparation and lifecycle commands without private entitlements; the separately signed vphone-vm carries the entitlements needed to run the research guest. The Core Bundle asset is available if you prefer to use the CLI directly.

Setup With a Narrow Privilege Boundary

Launchpad separates host checks, bundle installation, and VM creation into visible steps with progress and logs. Its privileged helper has fixed operations for managing verified bundle releases, admitting a receipt-checked VM executable through AMFI, and installing guest changes from the installed bundle. It checks the published download hash, code signature, and installed receipt before using the bundle. Each new VM executable signature is checked separately. The Recovery settings above still require the machine owner; Launchpad handles the remaining host setup and authorization prompts.

Upgrading From 1.x

Version 2 uses a new VM format and cannot start VMs created by 1.x. Create a new VM with Launchpad or vphone-cli vm create; there is no in-place conversion. Keep 1.x if you need to run an older VM.

The notarized Launchpad archive is the recommended download for 2.0.4. The Core Bundle is a separate asset, which Launchpad can download and install for you. For commands and advanced setup, see the README and create and run guide.