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

> Understand the vphone-cli firmware variants: Regular, Development, Jailbreak, and Experimental. Learn which build suits your needs and how to select them.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: deep-dive
- Published: 2026-09-09

---

**vPhone-CLI ships four distinct firmware variants—Regular, Development, Jailbreak, and Experimental—each defined in [`AGENTS.md`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
make fw_patch
make cfw_install

```

Alternatively, use the host-mounted shortcut:

```bash
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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main//cores/vphone_jb_setup.sh). To compile and install:

```bash
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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_prepare.sh), [`scripts/patchers/cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py), and [`scripts/cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh).

### Firmware Preparation

The `make fw_prepare` command executes [`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main//cores/vphone_jb_setup.sh), requiring no manual intervention after running `make cfw_install_jb`.