VPhone-CLI Firmware Variants Explained: Regular, Dev, Jailbreak, and Experimental

TLDR: VPhone-CLI provides four distinct firmware variants—Regular (52 patches), Development (66 patches), Jailbreak (127 patches), and Experimental (141 patches)—that control binary modifications to the iOS kernel, the number of build phases, and which additional services like RPC servers or Procursus toolchains are installed inside the virtual machine.

VPhone-CLI by Lakr233 is an open-source tool for running virtualized iOS environments. These vphone-cli firmware variants determine how the iOS VM is patched and which software components are included, ranging from baseline boot capability to full jailbreak environments with experimental research patches.

Firmware Variant Overview

The repository distributes four pre-built configurations that differ in patch count, build phases, and installed components. The "Regular" variant represents the minimal or "less" patched option, while subsequent tiers add functionality for development and research.

Variant	Patches	Phases	Key Components	Best For
Regular	52	10	Plain custom firmware (CFW)	Baseline VM running stock iOS
Development	66	12	CFW + RPC-server daemon	Remote debugging and scripting
Jailbreak	127	14	CFW + jetsam-fix + Procursus	Root access and unsigned code execution
Experimental	141	18	All JB features + research patches	Testing device-tree identity tweaks

Patch Count and Build Phase Differences

The primary distinction between variants lies in how many binary modifications are applied to the iOS kernel, DSC (Device Secure Controller), and other firmware blobs during the build process.

Regular applies only the essential patches required for the VM to start—52 modifications across 10 build phases—creating a stable, stock-like environment with minimal deviation from official firmware.

Development adds 14 additional patches (66 total) across 12 phases to support the RPC-server daemon, enabling persistent host-side communication channels for debugging.

Jailbreak introduces comprehensive patches totaling 127 across 14 phases, including jetsam memory fixes and Procursus toolchain integration, creating a full jailbreak environment with package managers and root filesystem access.

Experimental applies 141 patches across 18 phases, adding research-grade modifications on top of the jailbreak base. These include hv_vmm renames and device-tree identity tweaks that make the VM appear less virtual while preserving graphics acceleration paths.

Technical Implementation in Source Code

Variant selection is handled at runtime by sources/vphone-cli/VPhoneFirmwareSelection.swift. According to the source code, the CLI parses the --variant flag in VPhoneFWCLI.swift and maps it to a specific firmware binary.

The selection logic loads the appropriate *.im4p CFW binary and determines which launch-daemons start inside the VM based on the enum value passed to VPhoneFirmwareSelection.firmwarePath(for:).

// From sources/vphone-cli/VPhoneFirmwareSelection.swift
let selected = VPhoneFirmwareSelection.Variant(rawValue: args.variant) ?? .regular
let fwPath = VPhoneFirmwareSelection.firmwarePath(for: selected)

Variant-Specific Installation Scripts

Each firmware variant is assembled by dedicated installer scripts in the scripts/ directory:

• scripts/cfw_install.sh — Builds the Regular variant with baseline patches only.
• scripts/cfw_install_dev.sh — Assembles the Development variant, adding the RPC-server daemon to the regular CFW.
• scripts/cfw_install_jb.sh — Creates the Jailbreak variant by applying jetsam fixes and integrating the Procursus jailbreak environment.
• scripts/cfw_install_exp.sh — Produces the Experimental variant by layering research patches on top of the full jailbreak firmware.

CLI Usage Examples

Select your desired firmware variant using the --variant flag when booting the VM. The CLI entry point in sources/vphone-cli/VPhoneFWCLI.swift parses this argument and delegates to the firmware selection layer.

# Boot with Regular firmware (default, minimal patches)

vphone-cli boot

# Boot with Development firmware (includes rpcserver)

vphone-cli boot --variant dev

# Boot with Jailbreak firmware (full root access)

vphone-cli boot --variant jb

# Boot with Experimental firmware (research patches)

vphone-cli boot --variant exp

The AGENTS.md file in the repository root documents the complete firmware table, patch counts, and phase descriptions for each variant.

Summary

• Regular (52 patches/10 phases) provides the minimal patch set required to boot stock iOS in a VM with no additional services.
• Development (66 patches/12 phases) adds an RPC-server daemon for remote debugging and host-side scripting capabilities.
• Jailbreak (127 patches/14 phases) delivers a complete jailbreak environment with Procursus toolchain integration and jetsam memory fixes.
• Experimental (141 patches/18 phases) includes bleeding-edge research patches for device identity modification and virtualization detection bypass.
• Selection logic resides in sources/vphone-cli/VPhoneFirmwareSelection.swift, while build scripts live in scripts/cfw_install*.sh.

Frequently Asked Questions

What is the difference between the Jailbreak and Experimental variants?

The Jailbreak variant provides a stable jailbreak environment with 127 patches, including Procursus integration and jetsam fixes for running unsigned code. The Experimental variant adds 14 additional research-grade patches (141 total) that modify identifiers like hv_vmm and device-tree identities to make the VM appear less virtual to Apple services, intended specifically for security researchers testing device fingerprinting bypasses.

Which firmware variant should I use for iOS app development?

Use the Development variant. According to scripts/cfw_install_dev.sh, this configuration includes the RPC-server daemon—a lightweight remote-control service that enables persistent host-side debugging and automation scripting capabilities not available in the Regular variant.

How do I switch between firmware variants when booting the VM?

Pass the --variant flag to the vphone-cli boot command with values regular, dev, jb, or exp. The CLI entry point in sources/vphone-cli/VPhoneFWCLI.swift parses this argument and passes it to VPhoneFirmwareSelection.firmwarePath(for:) to load the correct *.im4p binary. Omitting the flag defaults to the Regular variant.

Where are the firmware variant definitions documented in the source code?

The authoritative reference is AGENTS.md in the repository root, which contains the firmware table mapping variants to patch counts and build phases. The runtime selection logic is implemented in sources/vphone-cli/VPhoneFirmwareSelection.swift, while the build scripts for each variant are located in scripts/cfw_install.sh, scripts/cfw_install_dev.sh, scripts/cfw_install_jb.sh, and scripts/cfw_install_exp.sh.

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