How to Perform a Full End-to-End Setup with vphone-cli: Complete Virtual iPhone Automation Guide

vphone-cli automates the complete virtual iPhone lifecycle—from downloading iOS IPSWs and merging CloudOS components to patching firmware, performing DFU restores, and booting jailbroken VMs—using a single vm create command orchestrated through Makefile targets and Swift-based tooling.

This guide walks through the full end-to-end setup with vphone-cli, the open-source macOS tool that leverages Apple’s Virtualization.framework to run virtual iPhones. Whether you need a development sandbox, a jailbroken testing environment, or a research platform, understanding the underlying pipeline helps you troubleshoot failures and customize the build process.

Install Host Prerequisites and Toolchain

Before creating your first virtual device, you must install dependencies and build auxiliary tools. The repository uses a Makefile to coordinate environment setup across shell scripts and Swift sources.

Run the initial setup:

make setup_tools

This target executes scripts/setup_tools.sh, which performs three critical operations:

• Installs Homebrew packages required for image handling and cryptographic operations
• Compiles the trustcache and insert_dylib binaries from source
• Invokes scripts/setup_venv.sh to create an isolated Python virtual environment with Capstone, Keystone, and pyimg4 dependencies listed in requirements.txt

The Python venv is essential for the pymobiledevice3_bridge.py script used later during the restore phase. Verify your environment by checking that ~/.vphone/venv exists and contains the required packages.

Create a VM Bundle and Configuration

With the toolchain ready, generate a new virtual machine directory structure. The VM bundle stores manifests, disk images, and firmware caches under ~/.vphone/VMs/<name>/.

Initialize a new device named "research-phone":

vphone-cli vm create research-phone -V jb

The vm create command (implemented in sources/vphone-cli/VPhoneCLI.swift) triggers make vm_new internally, which runs scripts/vm_create.sh. This script generates a config.plist manifest based on the Swift model in sources/VPhoneCore/VPhoneVirtualMachineManifest.swift, recording CPU core allocation, memory size, and disk capacity.

Prepare and Merge Firmware Images

vphone-cli requires two IPSW archives: the standard iPhone firmware and the CloudOS root filesystem. The preparation stage downloads, extracts, and merges these components.

Execute the firmware pipeline:

make fw_prepare

The scripts/fw_prepare.sh shell script (coordinated through sources/VPhoneCore/VPhoneResources.swift) performs the following:

1. Downloads the target iPhone IPSW and CloudOS IPSW to ~/.vphone/ipsws/
2. Extracts both archives using standard compression tools
3. Merges the CloudOS rootfs into the iPhone bundle, creating a unified filesystem structure required for the virtual device

This merged bundle serves as the base for the patching stage. Ensure you have sufficient disk space in ~/.vphone/; the extracted firmware can exceed 15 GB per version.

Patch the Boot Chain with Firmware Variants

The FirmwarePatcher Swift module modifies the boot chain to enable debugging, jailbreaking, or experimental features. vphone-cli supports five distinct variants: regular, dev, jb (jailbreak), exp (experimental), and less.

Apply the jailbreak patch set:

make fw_patch_jb

This target compiles and executes the patcher located in sources/FirmwarePatcher/. Key components include:

• sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift: Implements kernel-level jailbreak patches, including code signing bypasses and sandbox modifications
• sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift: Modifies DeviceTree entries to support modified boot arguments
• Boot components: Updates iBSS, iBEC, LLB, and TXM (Trusted Execution Monitor) binaries

The patcher generates a modified firmware bundle ready for restoration. For research details on binary modifications, reference research/0_binary_patch_comparison.md in the repository.

Enter DFU Mode and Acquire SHSH Blobs

To install the modified firmware, the virtual device must enter Device Firmware Update (DFU) mode and obtain signed SHSH blobs from Apple’s TSS server.

Launch the VM in DFU mode:

make boot_dfu

Alternatively, use the CLI directly:

vphone-cli vm launch research-phone --dfu

The --dfu flag (handled in sources/vphone-cli/VPhoneVirtualMachine.swift) configures the virtual USB stack to present the device as a DFU target to the host.

While the VM runs in DFU mode, request SHSH blobs:

make restore_get_shsh

This executes scripts/pymobiledevice3_bridge.py, which uses the pymobiledevice3 library to communicate with Apple’s TSS server and save the signed blobs required for a verified restore.

Restore the iOS Image via DFU

With blobs obtained, perform the actual firmware restoration. The restore process decrypts AEA-encrypted images on-the-fly and flashes the patched firmware to the virtual device.

Execute the restore:

make restore

For offline restoration using cached blobs:

make restore_offline

The restoration logic spans two components:

• scripts/pymobiledevice3_bridge.py: Python bridge handling USB communication and TSS transactions
• sources/VPhoneCore/VPhoneRestoreOps.swift: Swift implementation coordinating the restoration state machine with the Virtualization.framework backend

Monitor the terminal output for progress indicators; restoration of a 15 GB firmware bundle typically takes 8–15 minutes depending on host I/O performance.

Install Custom Firmware (CFW) on the Host

After restoring the base iOS image, you must install the Custom Firmware (CFW)—the patched system files generated during the boot chain modification phase. This step requires host-level filesystem access and elevated privileges.

Install the CFW:

make cfw_install

The scripts/cfw_install_host.sh script performs these operations:

1. Mounts the VM’s raw disk image on the macOS host using hdiutil
2. Copies patched kernel, bootloader, and system partition files from ~/.vphone/ipsws/ into the mounted volume
3. Executes the boot snapshot flip, marking the new system image as active for the next boot cycle
4. Unmounts the disk image cleanly

This step requires sudo access to manipulate virtual disk attachments. For details on launchd and jetsam modifications included in the CFW, consult research/cfw_patch_launchd_jetsam.md.

First Boot and Jailbreak Automation

With the CFW installed, launch the virtual device normally:

make boot

Or via CLI:

vphone-cli vm launch research-phone

If you selected the jb variant during creation, the jailbreak automatically activates on first boot. The system installs Sileo, TrollStore, and auxiliary tooling without manual intervention. The boot process is managed by sources/vphone-cli/VPhoneVirtualMachine.swift, while post-boot app installation logic resides in sources/vphone-cli/VPhoneMenuApps.swift.

Once the VM reaches the home screen, you have a fully functional, jailbroken virtual iPhone environment suitable for iOS security research, app debugging, or tweak development.

Summary

• vphone-cli orchestrates ten distinct stages—from toolchain installation through jailbreak automation—using a combination of Makefile targets, shell scripts, and Swift-based Virtualization.framework wrappers.
• The vm create command executes steps 3–9 automatically (firmware preparation, patching, restore, and CFW installation), though individual stages can be run manually via make fw_prepare, make fw_patch, make restore, and make cfw_install.
• Critical host-side operations reside in scripts/setup_tools.sh, scripts/fw_prepare.sh, and scripts/cfw_install_host.sh, while core virtualization logic is implemented in sources/VPhoneCore/ and sources/vphone-cli/.
• Python bridging for device restoration uses scripts/pymobiledevice3_bridge.py with the pymobiledevice3 library to handle DFU communication and SHSH blob acquisition.
• Firmware patching is variant-aware (regular, dev, jb, exp, less) and modifies boot components including iBSS, iBEC, LLB, kernel, and DeviceTree via the FirmwarePatcher Swift module.

Frequently Asked Questions

What are the minimum system requirements for vphone-cli?

You need a Mac running macOS 15 (Sequoia) or later with Apple Silicon or an Intel processor that supports Apple’s Virtualization.framework. The host requires approximately 50 GB of free disk space for IPSW downloads, extracted firmware, and VM disk images, plus sufficient RAM to allocate 4–8 GB to the virtual device.

How do I choose between jailbreak and non-jailbreak variants?

Use the -V flag when creating the VM. Pass -V jb for the jailbreak variant (which installs Sileo and TrollStore automatically), -V dev for development kernels with debug symbols, or -V regular for a stock iOS experience. The variant selection determines which Makefile target runs during fw_patch (e.g., make fw_patch_jb vs make fw_patch).

Can I manually re-run individual setup stages if something fails?

Yes. While vphone-cli vm create runs the full pipeline sequentially, you can execute individual stages using Makefile targets: make fw_prepare to re-download firmware, make fw_patch_jb to re-apply patches, make restore to re-flash the device, or make cfw_install to re-install custom firmware after modifying patches.

Why does the DFU restore step fail with SHSH errors?

This usually indicates a mismatch between the firmware version being restored and the blobs obtained from Apple’s TSS server. Ensure you run make restore_get_shsh while the VM is actively in DFU mode (launched via make boot_dfu) and before the TSS window closes. The scripts/pymobiledevice3_bridge.py script must successfully communicate with the virtual USB device presented by sources/vphone-cli/VPhoneVirtualMachine.swift to retrieve valid blobs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}