vphone-cli Firmware Variants Explained: Regular, Dev, Jailbreak, Experimental, and Research

The five firmware variants in vphone-cli—regular, dev, jb, exp, and research—form a layered stack of progressively aggressive patches, ranging from minimal boot-chain fixes to full kernel hooks and VM-hiding DSC modifications.

vphone-cli is an open-source virtualization tool for creating and managing iOS virtual machines. The --variant flag controls which firmware patches are applied to the boot chain, kernel cache, and Dynamic System Components (DSC) before the VM starts.

The Five Firmware Variants in vphone-cli

The source code defines five distinct patching profiles. Four are accessible via the CLI --variant flag, while the fifth is used internally by the patcher.

• regular: The baseline "vanilla" VM with minimal patches—only essential boot-chain signature bypasses, APFS snapshot handling, and basic sandbox hooks.
• dev: Adds developer-mode patches on top of regular, including the EXC-GUARD helper (patch 27) and selector‑24 bypasses for debugging.
• jb (jailbreak): Includes every JB‑Only kernel method (patches JB‑01 through JB‑29), removing AMFI cdhash checks, relaxing sandbox policies, and enabling task_for_pid.
• exp (experimental): A superset of jailbreak that adds EXP‑Only patches—kernel renaming, DSC c‑string mangling, device‑tree identity rewrites, camera-app accessibility fixes, and watchdog‑d modifications.
• research: An implicit variant not exposed as a CLI flag; it targets the txm.research.im4p image and differs only in the embedded iboot-build-variant string, otherwise behaving identically to regular.

Architectural Differences by Component

Boot-Chain Patches

All five variants share the same boot-loader patches for AVPBooter, iBSS, iBEC, LLB, and TXM, including signature bypasses and serial-label injection. As documented in research/0_binary_patch_comparison.md, the experimental variant does not add extra boot-chain changes beyond those present in the jailbreak variant. The research variant differs solely in its iboot-build-variant identifier, making it functionally equivalent to regular at the binary level.

Kernel-Cache Modifications

The kernel-cache patching strategy escalates across variants:

• Regular and Dev: Apply core base patches such as NOPs for APFS mount checks and sandbox-hook stubs. Dev additionally activates the EXC‑GUARD helper and optional developer-mode bypasses.
• Jailbreak: Executes all JB-* patches, which disable code-signing enforcement, extend sandbox hooks, and allow privileged operations like task_for_pid.
• Experimental: Runs the full jailbreak patch set, then applies EXP‑Only kernel patches including patch_hv_vmm_rename to hide the hypervisor presence.

Device-Tree Rewrites

Only the experimental variant performs device-tree (DT) rewrites at fw-patch time. According to the patch comparison tables in research/0_binary_patch_comparison.md, it flips eight identity-related DT properties to spoof the model as D47AP / iPhone17,3, masking the virtual machine's hardware identity from Apple services.

DSC and User-Space Patches

Dynamic System Components (DSC) and user-space modifications follow a strict hierarchy:

• Regular and Dev: No DSC changes.
• Jailbreak: No DSC changes.
• Experimental: Performs byte‑5 mangling of the kern.hv_vmm_present c‑string, per-page re‑attestation, and a watchdog‑d patch that forces the "am I a VM?" flag to 1. It also injects extensive camera-app accessibility patches under /product/camera and rewrites ProductBuildVersion when SPOOF_BUILD is enabled.

How to Select Firmware Variants in vphone-cli

Specify the variant during VM creation or firmware patching using the -V or --variant flags. The CLI implementation in sources/vphone-cli/VPhoneFWCLI.swift parses these options and routes them to the appropriate patching pipeline.

Create a new VM with a specific firmware variant:

# Baseline firmware with minimal patches

vphone-cli vm create myphone -V regular

# Developer mode with EXC-GUARD support

vphone-cli vm create myphone -V dev

# Full jailbreak patches

vphone-cli vm create myphone -V jb

# Experimental patches (jailbreak + VM hiding)

vphone-cli vm create myphone -V exp

Patch or install custom firmware (CFW) for an existing VM:

# Patch existing firmware to jailbreak variant

vphone-cli fw patch myphone --variant jb

# Install experimental CFW using the dedicated script

vphone-cli cfw install myphone --variant exp

The repository provides dedicated installation scripts for each variant—cfw_install.sh, cfw_install_dev.sh, cfw_install_jb.sh, and cfw_install_exp.sh—located in the scripts/ directory.

Summary

• Five total variants exist: regular, dev, jb, exp, and the internal research variant.
• Progressive layering defines the architecture: regular adds base patches, dev adds debugging aids, jb adds full kernel hooks, and exp adds VM-hiding DSC and device-tree modifications.
• Experimental uniquely modifies the device-tree identity, DSC c‑strings, and camera accessibility frameworks to mask the VM from host detection.
• Research is functionally identical to regular but targets a different TXM image internally.

Frequently Asked Questions

What is the difference between the jailbreak and experimental firmware variants?

The experimental variant is a strict superset of jailbreak. It executes all JB‑01 through JB‑29 patches, then adds EXP‑Only modifications including patch_hv_vmm_rename, DSC-level kern.hv_vmm_present c‑string mangling, watchdog‑d patches, and device-tree rewrites to D47AP. These additional layers hide the VM presence from Apple services while preserving graphics and compute paths.

Why does the research variant not have a CLI flag?

The research variant is reserved for internal patcher operations targeting txm.research.im4p. As noted in research/0_binary_patch_comparison.md, it is not exposed via --variant because it differs from regular only in the embedded iboot-build-variant string and is functionally identical otherwise.

Which vphone-cli firmware variant should I use for basic iOS testing?

Use the regular variant for basic testing and stability. It applies only the essential patches required to boot iOS—boot-chain signature bypasses and APFS snapshot handling—without the security relaxations or debugging overhead present in dev, jb, or exp variants.

Can I switch firmware variants without recreating the VM?

Yes. You can re-patch an existing VM using vphone-cli fw patch <vm-name> --variant <type> or reinstall CFW with vphone-cli cfw install <vm-name> --variant <type>. This overwrites the boot chain, kernel cache, and DSC modifications without destroying the virtual disk or configuration.

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