vPhone-CLI Firmware Variants: Regular, Development, Jailbreak, and Experimental Builds Explained

vPhone-CLI ships four distinct firmware variants—Regular, Development, Jailbreak, and Experimental—each defined in AGENTS.md and selectable via dedicated Make targets that apply specific combinations of boot-chain patches and custom firmware (CFW) phases.

The Lakr233/vphone-cli repository provides a virtualization toolkit for iPhone research that supports multiple firmware configurations tailored to different experimental needs. Each firmware variant in vphone-cli represents a specific set of boot-chain patches and CFW phases, allowing researchers to select precisely the level of system modification required. According to the source code in AGENTS.md, these variants range from baseline research configurations to heavily modified experimental builds designed to evade VM detection.

Overview of the Four Firmware Variants

The vphone-cli firmware variants are differentiated by the number of boot-chain patches applied and the complexity of the CFW installation phases. The Makefile defines specific targets for each variant, invoking the patcher_build binary through scripts/patchers/cfw.py with appropriate flags.

Regular Variant

The Regular variant serves as the baseline configuration for standard virtualization research. It applies 52 boot-chain patches and installs a 10-phase CFW that provides essential virtualization and networking components.

This variant is suitable for most research scenarios requiring basic VM functionality without extensive system modification. To build and install this variant, use:

make fw_patch
make cfw_install

Alternatively, use the host-mounted shortcut:

make cfw_install_host VARIANT=regular

Development Variant

The Development variant extends the regular configuration with additional patches required for "dev-mode" TXM (Trusted Execution Mode) firmware. It incorporates 66 boot-chain patches and a 12-phase CFW, enabling early-access features useful for active development and debugging.

The extra patches in this variant facilitate deeper system introspection and modified trust zone behaviors. Build this variant using:

make fw_patch_dev
make cfw_install_dev

Jailbreak Variant

The Jailbreak variant builds upon the regular configuration by inserting the complete jailbreak (JB) toolchain. It applies 127 boot-chain patches and deploys a 14-phase CFW that includes jetsam fixes, the Procursus package manager, and additional binary utilities.

On first boot, this variant automatically finalizes jailbreak setup via the launch daemon /cores/vphone_jb_setup.sh. To compile and install:

make fw_patch_jb
make cfw_install_jb

For optional Frida support during patch application, append FRIDA=1 to the make fw_patch_jb command.

Experimental Variant

The Experimental variant represents the most feature-rich and heavily modified configuration. It contains all JB patches plus experimental research modifications including kernel hv_vmm renaming, DSC byte-5 mangling, surgical watchdogd fixes, DT identity tweaks, post-restore DT rewriting, and optional build-spoofing capabilities.

With 141 boot-chain patches and 18 CFW phases, this variant is designed for advanced research where the VM must appear less VM-like to Apple services while retaining graphics and compute acceleration. Build commands include:

make fw_patch_exp
make cfw_install_exp

To include build-spoofing (e.g., reporting as build 23F77), add SPOOF_BUILD=23F77 to both commands.

Build Pipeline Architecture

All firmware variants share a unified three-stage pipeline implemented across scripts/fw_prepare.sh, scripts/patchers/cfw.py, and scripts/cfw_install_host.sh.

Firmware Preparation

The make fw_prepare command executes scripts/fw_prepare.sh to download the IPSW, merge CloudOS components, and initialize the working directory (VM_DIR).

Patch Application

The fw_patch* targets invoke the Swift-based patcher_build binary through scripts/patchers/cfw.py, applying variant-specific patches to the boot chain. The patcher selects the appropriate patch set based on the Make target invoked.

CFW Installation

Host-mount scripts (scripts/cfw_install_host.sh) copy the patched files into the VM disk and flip the boot snapshot offline. The VM must be powered off when running any cfw_install_* target.

Complete Build Examples

The following examples demonstrate complete workflows for each vphone-cli firmware variant:

# Regular variant with host-mounted installation

make fw_prepare
make fw_patch
make cfw_install_host VARIANT=regular

# Development variant

make fw_patch_dev
make cfw_install_dev

# Jailbreak variant with Frida instrumentation

make fw_patch_jb FRIDA=1
make cfw_install_jb

# Experimental variant with custom build spoofing

make fw_patch_exp SPOOF_BUILD=23F77
make cfw_install_exp SPOOF_BUILD=23F77

Summary

• Four distinct variants: Regular (52 patches/10 phases), Development (66/12), Jailbreak (127/14), and Experimental (141/18).
• Configuration source: Variant definitions and patch counts are documented in AGENTS.md at the repository root.
• Build system: The Makefile provides dedicated targets (fw_patch, fw_patch_dev, fw_patch_jb, fw_patch_exp) that drive the Swift-based patcher.
• Installation pipeline: scripts/cfw_install_host.sh handles host-mounted disk operations, requiring the VM to be offline during CFW installation.
• Use case progression: From baseline virtualization (Regular) to full jailbreak with JB toolchain (Jailbreak) to advanced anti-detection research (Experimental).

Frequently Asked Questions

How do I choose between the Regular and Experimental firmware variants?

Select the Regular variant for standard virtualization research requiring minimal system modification and stable networking. Choose the Experimental variant only when you require advanced anti-detection features like kernel hv_vmm renaming or DSC mangling to make the VM appear as physical hardware to Apple services. The Experimental variant's 141 patches may introduce instability not present in the Regular variant's 52-patch configuration.

What is the difference between make cfw_install and make cfw_install_host?

The make cfw_install target performs standard CFW installation procedures, while make cfw_install_host specifically uses scripts/cfw_install_host.sh to mount the VM disk on the host and inject the custom firmware directly. The host-mounted approach requires the VARIANT parameter (e.g., VARIANT=regular) and allows offline disk manipulation without running the VM.

Can I switch between firmware variants without rebuilding the base IPSW?

Yes, you can switch variants by re-running the appropriate fw_patch* target followed by the corresponding cfw_install* command. However, you must first run make fw_prepare to establish the base firmware working directory (VM_DIR). Each patch target applies a different patch set from scripts/patchers/cfw.py to the same base IPSW, allowing variant switching without re-downloading the original firmware.

Does the Jailbreak variant include the Procursus package manager automatically?

Yes, the Jailbreak variant's 14-phase CFW includes the Procursus package manager and related binaries as part of its boot-chain patches. The jailbreak finalization occurs automatically on first boot via /cores/vphone_jb_setup.sh, requiring no manual intervention after running make cfw_install_jb.

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