# How to Perform a Full End-to-End Setup with vphone-cli: Complete Virtual iPhone Automation Guide

> Automate virtual iPhone setup with vphone-cli. Learn the end-to-end process from IPSW download to jailbroken VM boot using one command. Simplify your workflow today.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-12

---

**vphone-cli automates the complete virtual iPhone lifecycle—from downloading iOS IPSWs and merging CloudOS components to patching firmware, performing DFU restores, and booting jailbroken VMs—using a single `vm create` command orchestrated through Makefile targets and Swift-based tooling.**

This guide walks through the full **end-to-end setup with vphone-cli**, the open-source macOS tool that leverages Apple’s Virtualization.framework to run virtual iPhones. Whether you need a development sandbox, a jailbroken testing environment, or a research platform, understanding the underlying pipeline helps you troubleshoot failures and customize the build process.

## Install Host Prerequisites and Toolchain

Before creating your first virtual device, you must install dependencies and build auxiliary tools. The repository uses a **Makefile** to coordinate environment setup across shell scripts and Swift sources.

Run the initial setup:

```bash
make setup_tools

```

This target executes [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh), which performs three critical operations:

- Installs Homebrew packages required for image handling and cryptographic operations
- Compiles the `trustcache` and `insert_dylib` binaries from source
- Invokes [`scripts/setup_venv.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_venv.sh) to create an isolated Python virtual environment with Capstone, Keystone, and pyimg4 dependencies listed in [`requirements.txt`](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt)

The Python venv is essential for the [`pymobiledevice3_bridge.py`](https://github.com/Lakr233/vphone-cli/blob/main/pymobiledevice3_bridge.py) script used later during the restore phase. Verify your environment by checking that `~/.vphone/venv` exists and contains the required packages.

## Create a VM Bundle and Configuration

With the toolchain ready, generate a new virtual machine directory structure. The **VM bundle** stores manifests, disk images, and firmware caches under `~/.vphone/VMs/<name>/`.

Initialize a new device named "research-phone":

```bash
vphone-cli vm create research-phone -V jb

```

The `vm create` command (implemented in [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift)) triggers `make vm_new` internally, which runs [`scripts/vm_create.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vm_create.sh). This script generates a `config.plist` manifest based on the Swift model in [`sources/VPhoneCore/VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneVirtualMachineManifest.swift), recording CPU core allocation, memory size, and disk capacity.

## Prepare and Merge Firmware Images

vphone-cli requires two IPSW archives: the standard iPhone firmware and the CloudOS root filesystem. The preparation stage downloads, extracts, and merges these components.

Execute the firmware pipeline:

```bash
make fw_prepare

```

The [`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_prepare.sh) shell script (coordinated through [`sources/VPhoneCore/VPhoneResources.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneResources.swift)) performs the following:

1. Downloads the target iPhone IPSW and CloudOS IPSW to `~/.vphone/ipsws/`
2. Extracts both archives using standard compression tools
3. Merges the CloudOS rootfs into the iPhone bundle, creating a unified filesystem structure required for the virtual device

This merged bundle serves as the base for the patching stage. Ensure you have sufficient disk space in `~/.vphone/`; the extracted firmware can exceed 15 GB per version.

## Patch the Boot Chain with Firmware Variants

The **FirmwarePatcher** Swift module modifies the boot chain to enable debugging, jailbreaking, or experimental features. vphone-cli supports five distinct variants: `regular`, `dev`, `jb` (jailbreak), `exp` (experimental), and `less`.

Apply the jailbreak patch set:

```bash
make fw_patch_jb

```

This target compiles and executes the patcher located in `sources/FirmwarePatcher/`. Key components include:

- **[`sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift)**: Implements kernel-level jailbreak patches, including code signing bypasses and sandbox modifications
- **[`sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift)**: Modifies DeviceTree entries to support modified boot arguments
- **Boot components**: Updates iBSS, iBEC, LLB, and TXM (Trusted Execution Monitor) binaries

The patcher generates a modified firmware bundle ready for restoration. For research details on binary modifications, reference [`research/0_binary_patch_comparison.md`](https://github.com/Lakr233/vphone-cli/blob/main/research/0_binary_patch_comparison.md) in the repository.

## Enter DFU Mode and Acquire SHSH Blobs

To install the modified firmware, the virtual device must enter **Device Firmware Update (DFU) mode** and obtain signed SHSH blobs from Apple’s TSS server.

Launch the VM in DFU mode:

```bash
make boot_dfu

```

Alternatively, use the CLI directly:

```bash
vphone-cli vm launch research-phone --dfu

```

The `--dfu` flag (handled in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift)) configures the virtual USB stack to present the device as a DFU target to the host.

While the VM runs in DFU mode, request SHSH blobs:

```bash
make restore_get_shsh

```

This executes [`scripts/pymobiledevice3_bridge.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/pymobiledevice3_bridge.py), which uses the `pymobiledevice3` library to communicate with Apple’s TSS server and save the signed blobs required for a verified restore.

## Restore the iOS Image via DFU

With blobs obtained, perform the actual firmware restoration. The restore process decrypts AEA-encrypted images on-the-fly and flashes the patched firmware to the virtual device.

Execute the restore:

```bash
make restore

```

For offline restoration using cached blobs:

```bash
make restore_offline

```

The restoration logic spans two components:

- **[`scripts/pymobiledevice3_bridge.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/pymobiledevice3_bridge.py)**: Python bridge handling USB communication and TSS transactions
- **[`sources/VPhoneCore/VPhoneRestoreOps.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneRestoreOps.swift)**: Swift implementation coordinating the restoration state machine with the Virtualization.framework backend

Monitor the terminal output for progress indicators; restoration of a 15 GB firmware bundle typically takes 8–15 minutes depending on host I/O performance.

## Install Custom Firmware (CFW) on the Host

After restoring the base iOS image, you must install the **Custom Firmware (CFW)**—the patched system files generated during the boot chain modification phase. This step requires host-level filesystem access and elevated privileges.

Install the CFW:

```bash
make cfw_install

```

The [`scripts/cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh) script performs these operations:

1. Mounts the VM’s raw disk image on the macOS host using `hdiutil`
2. Copies patched kernel, bootloader, and system partition files from `~/.vphone/ipsws/` into the mounted volume
3. Executes the **boot snapshot flip**, marking the new system image as active for the next boot cycle
4. Unmounts the disk image cleanly

This step requires `sudo` access to manipulate virtual disk attachments. For details on launchd and jetsam modifications included in the CFW, consult [`research/cfw_patch_launchd_jetsam.md`](https://github.com/Lakr233/vphone-cli/blob/main/research/cfw_patch_launchd_jetsam.md).

## First Boot and Jailbreak Automation

With the CFW installed, launch the virtual device normally:

```bash
make boot

```

Or via CLI:

```bash
vphone-cli vm launch research-phone

```

If you selected the `jb` variant during creation, the jailbreak automatically activates on first boot. The system installs **Sileo**, **TrollStore**, and auxiliary tooling without manual intervention. The boot process is managed by [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), while post-boot app installation logic resides in [`sources/vphone-cli/VPhoneMenuApps.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneMenuApps.swift).

Once the VM reaches the home screen, you have a fully functional, jailbroken virtual iPhone environment suitable for iOS security research, app debugging, or tweak development.

## Summary

- **vphone-cli** orchestrates ten distinct stages—from toolchain installation through jailbreak automation—using a combination of Makefile targets, shell scripts, and Swift-based Virtualization.framework wrappers.
- The **`vm create`** command executes steps 3–9 automatically (firmware preparation, patching, restore, and CFW installation), though individual stages can be run manually via `make fw_prepare`, `make fw_patch`, `make restore`, and `make cfw_install`.
- Critical host-side operations reside in [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh), [`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_prepare.sh), and [`scripts/cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh), while core virtualization logic is implemented in `sources/VPhoneCore/` and `sources/vphone-cli/`.
- Python bridging for device restoration uses [`scripts/pymobiledevice3_bridge.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/pymobiledevice3_bridge.py) with the `pymobiledevice3` library to handle DFU communication and SHSH blob acquisition.
- Firmware patching is variant-aware (`regular`, `dev`, `jb`, `exp`, `less`) and modifies boot components including iBSS, iBEC, LLB, kernel, and DeviceTree via the **FirmwarePatcher** Swift module.

## Frequently Asked Questions

### What are the minimum system requirements for vphone-cli?

You need a Mac running **macOS 15 (Sequoia) or later** with Apple Silicon or an Intel processor that supports Apple’s Virtualization.framework. The host requires approximately 50 GB of free disk space for IPSW downloads, extracted firmware, and VM disk images, plus sufficient RAM to allocate 4–8 GB to the virtual device.

### How do I choose between jailbreak and non-jailbreak variants?

Use the `-V` flag when creating the VM. Pass `-V jb` for the jailbreak variant (which installs Sileo and TrollStore automatically), `-V dev` for development kernels with debug symbols, or `-V regular` for a stock iOS experience. The variant selection determines which Makefile target runs during `fw_patch` (e.g., `make fw_patch_jb` vs `make fw_patch`).

### Can I manually re-run individual setup stages if something fails?

Yes. While `vphone-cli vm create` runs the full pipeline sequentially, you can execute individual stages using Makefile targets: `make fw_prepare` to re-download firmware, `make fw_patch_jb` to re-apply patches, `make restore` to re-flash the device, or `make cfw_install` to re-install custom firmware after modifying patches.

### Why does the DFU restore step fail with SHSH errors?

This usually indicates a mismatch between the firmware version being restored and the blobs obtained from Apple’s TSS server. Ensure you run `make restore_get_shsh` while the VM is actively in DFU mode (launched via `make boot_dfu`) and before the TSS window closes. The [`scripts/pymobiledevice3_bridge.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/pymobiledevice3_bridge.py) script must successfully communicate with the virtual USB device presented by [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) to retrieve valid blobs.