Firmware Patch Variants in vPhone‑CLI: Regular, Development, Jailbreak, and Experimental

vPhone‑CLI provides four distinct firmware patch variants—Regular, Development, Jailbreak, and Experimental—that determine the number of kernel patches applied, the complexity of the custom firmware installation, and the specific Make targets used during the build process.

The Lakr233/vphone-cli repository manages iOS virtualization through a tiered patching system. Each firmware patch variant builds upon the previous one, adding incremental modifications to the kernel, boot chain, and virtual machine configuration. Understanding these variants allows researchers and developers to select the appropriate level of system modification for their specific use case, from basic virtualization to full jailbreak environments with experimental anti-detection features.

Overview of the Four Firmware Patch Variants

According to the repository’s AGENTS.md file, the four firmware patch variants differ in three primary metrics: boot‑chain patch count, CFW installation phases, and Make target names.

Variant	Boot‑chain patches	CFW phases	Make targets (build + install)
Regular	52 patches	10 phases	fw_patch + cfw_install
Development	66 patches	12 phases	fw_patch_dev + cfw_install_dev
Jailbreak	127 patches	14 phases	fw_patch_jb + cfw_install_jb
Experimental	141 patches	18 phases	fw_patch_exp + cfw_install_exp

Boot‑chain patches represent individual binary modifications applied to the iOS kernel and boot components. CFW phases indicate the number of installation steps the custom firmware installer executes while preparing the VM image. Higher-tier variants inherit all patches from lower tiers and add specialized modifications for research or jailbreak functionality.

Technical Breakdown of Each Variant

Regular Variant

The Regular variant applies 52 kernel patches and runs 10 CFW installation phases. This is the baseline firmware patch variant intended for clean, un‑jailbroken virtual machines. It establishes core virtualization capabilities without altering system security boundaries or adding jailbreak-specific services.

In scripts/fw_patch.sh, the base patching logic coordinates the application of these 52 patches to the kernel and iBoot components. The corresponding scripts/cfw_install.sh script handles the 10-phase installation process, which includes basic filesystem setup and virtualization layer configuration.

Development Variant

The Development variant extends the Regular tier with 14 additional patches (totaling 66) and 12 CFW phases. This firmware patch variant introduces an RPC server daemon and other debugging services useful for researchers requiring enhanced introspection capabilities inside the VM.

The scripts/fw_patch_dev.sh script orchestrates the development-specific patches, while scripts/cfw_install_dev.sh manages the additional installation phases. These extra steps configure development tools and diagnostic interfaces not present in the regular build.

Jailbreak Variant

The Jailbreak variant incorporates 127 patches across 14 CFW installation phases, representing a superset of the Development tier with full jailbreak enablement. This firmware patch variant applies jetsam fixes, procursus installation routines, and mandatory code-signing bypasses required for a functional jailbreak environment.

Key implementation details reside in scripts/fw_patch_jb.sh and scripts/cfw_install_jb.sh. The installer invokes /cores/vphone_jb_setup.sh during the finalization phase to configure the automatic jailbreak environment that activates on first boot.

Experimental Variant

The Experimental variant represents the most comprehensive firmware patch variant with 141 patches and 18 CFW phases. It extends the Jailbreak tier with research-focused kernel modifications and DSC (Dyld Shared Cache) patches designed to alter VM identity detection.

According to the source analysis, these experimental patches implement "hv_vmm rename / DT identity" modifications that make the virtual machine appear less like a virtual device to certain Apple services while preserving VM-specific features. The scripts/fw_patch_exp.sh and scripts/cfw_install_exp.sh scripts coordinate these advanced modifications.

Build Commands and Usage

Each firmware patch variant exposes dedicated Make targets that wrap the underlying shell scripts. The Makefile defines these entry points for consistent build orchestration.

# Regular variant (52 patches, 10 phases)

make fw_patch
make cfw_install

# Development variant (66 patches, 12 phases)

make fw_patch_dev
make cfw_install_dev

# Jailbreak variant (127 patches, 14 phases)

make fw_patch_jb
make cfw_install_jb

# Experimental variant (141 patches, 18 phases)

make fw_patch_exp
make cfw_install_exp

The Make targets invoke the corresponding scripts in the scripts/ directory:

• fw_patch.sh / cfw_install.sh – Base variant orchestration
• fw_patch_dev.sh / cfw_install_dev.sh – Development additions
• fw_patch_jb.sh / cfw_install_jb.sh – Jailbreak enablement
• fw_patch_exp.sh / cfw_install_exp.sh – Experimental research patches

Individual patch implementations reside in sources/FirmwarePatcher/, where Swift-based patchers modify specific kernel and iBoot binaries according to the selected variant’s requirements.

Key Source Files and Architecture

Understanding the firmware patch variants requires familiarity with these critical repository locations:

• AGENTS.md – Documents the variant matrix, patch counts, and target relationships
• Makefile – Defines the fw_patch* and cfw_install* targets that dispatch to shell scripts
• scripts/fw_patch*.sh – Shell orchestration scripts that apply kernel/boot patches (52, 66, 127, or 141 depending on variant)
• scripts/cfw_install*.sh – Installation scripts executing 10, 12, 14, or 18 CFW preparation phases
• sources/FirmwarePatcher/ – Swift implementations of binary patch logic for kernel, iBoot, and DSC modifications
• /cores/vphone_jb_setup.sh – Post-installation launch daemon invoked by Jailbreak and Experimental variants to finalize jailbreak state

Summary

• vPhone‑CLI offers four firmware patch variants (Regular, Development, Jailbreak, Experimental) that progressively increase system modification levels.
• Patch counts scale from 52 to 141, with each tier inheriting all modifications from previous tiers and adding specialized features.
• Make targets follow a predictable naming convention (fw_patch vs fw_patch_dev vs fw_patch_jb vs fw_patch_exp) to simplify variant selection.
• CFW installation phases range from 10 to 18, with higher tiers performing additional post-install configuration such as jailbreak setup and anti-detection modifications.
• Experimental variants include research-focused patches for VM identity masking while maintaining virtualization capabilities.

Frequently Asked Questions

What is the difference between the Jailbreak and Experimental firmware patch variants?

The Jailbreak variant applies 127 patches and configures a standard jailbreak environment with procursus and jetsam fixes. The Experimental variant adds 14 additional patches (totaling 141) that implement advanced research features like DSC/VM-identity patches and "hv_vmm rename" modifications designed to alter how Apple services detect the virtual machine.

Which firmware patch variant should I use for basic iOS virtualization research?

Use the Regular variant (52 patches, 10 phases) for baseline virtualization without jailbreak complications, or the Development variant (66 patches, 12 phases) if you require RPC services and debugging hooks. According to the AGENTS.md documentation, Regular provides a clean, un‑jailbroken VM suitable for testing App Store applications behavior.

Are the higher-tier firmware patch variants safe for production use?

The Experimental variant modifies VM identity detection mechanisms and applies 141 kernel patches, which may cause instability with certain Apple services. The repository documentation indicates these patches are research-focused; for stable jailbreak environments, the Jailbreak variant (127 patches) provides the necessary functionality without the experimental anti-detection modifications that could trigger security subsystem conflicts.

How do I switch between firmware patch variants without rebuilding from scratch?

You must run the appropriate make clean targets and rebuild using the specific variant targets (e.g., make fw_patch_jb instead of make fw_patch). Each variant uses distinct shell scripts (scripts/fw_patch*.sh) that apply non-overlapping patch sets; the build system does not support incremental switching between variants without re-executing the full patching pipeline.

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