explaingit

lakr233/vphone-cli

★ 5,996SwiftAudience · researcherComplexity · 5/5Setup · hard

TLDR

A command-line tool for Apple Silicon Macs that boots a virtual iPhone using Apple's own virtualization technology, letting researchers explore iOS internals without needing a physical device.

Mindmap

mindmap
  root((vphone-cli))
    What it does
      boots virtual iPhone
      patches iOS firmware
      supports jailbreak variant
    Requirements
      Apple Silicon Mac
      macOS Sequoia or later
      SIP and AMFI disabled
    Firmware Variants
      Patchless 3 patches
      Jailbreak 112 patches
      Sileo and TrollStore
    Use Cases
      iOS internals research
      boot chain experiments
      app install testing
    Audience
      security researchers
      iOS developers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Run a virtual iPhone on your Mac to study iOS internals without owning a physical device.

USE CASE 2

Boot a jailbroken virtual iPhone with Sileo and TrollStore pre-installed to experiment with additional software in a safe environment.

USE CASE 3

Test iOS firmware patches and boot chain modifications without risking a real device.

Tech stack

SwiftApple Virtualization frameworkiOS

Getting it running

Difficulty · hard Time to first run · 1day+

Requires disabling Apple's SIP and AMFI security layers on an Apple Silicon Mac running macOS Sequoia or later, not reversible without rebooting into recovery mode.

License terms are not described in the explanation.

In plain English

vphone-cli is a command-line tool that starts a virtual iPhone on a Mac. It uses Apple's own Virtualization framework, the same underlying technology Apple uses internally for its Private Compute Cloud research environment, to run an actual iOS system inside a virtual machine on macOS. The project has been tested on Apple Silicon Macs running macOS 26 (Sequoia) and later. To use it, the Mac needs certain security restrictions relaxed. Apple's System Integrity Protection (SIP) and a security layer called AMFI normally prevent unsigned software and private framework access, so the setup instructions walk through either disabling them or working around them with helper tools. This is a prerequisite because the virtualization entitlements the project needs are not granted to third-party software by default. The project provides four firmware variants with different levels of modification to the iOS boot chain. The lightest variant, called Patchless, makes three patches to the firmware and goes through two setup phases. The most extensive, called Jailbreak, applies 112 patches across 14 phases and sets up a package manager (Sileo) and an app installer (TrollStore) automatically on first boot, allowing users to install additional software on the virtual iPhone. Setup involves downloading iOS firmware files, patching the boot chain using the provided scripts, and then booting the virtual machine. The restore process requires two terminal windows running simultaneously: one keeps the virtual device in DFU mode (a special restore state) while the other sends the firmware. After that, first boot goes through a normal iOS startup sequence inside the virtual machine. The README notes tested hardware and firmware combinations. The project is under active development and is aimed at researchers interested in iOS internals.

Copy-paste prompts

Prompt 1
I've disabled SIP and AMFI on my Apple Silicon Mac. Walk me through downloading iOS firmware and patching it using the vphone-cli Patchless variant.
Prompt 2
My vphone-cli restore keeps failing during the DFU mode step. What should each of the two required terminal windows be running at the same time?
Prompt 3
Which vphone-cli firmware variant should I choose if I just want a clean virtual iOS environment without jailbreak, and how many setup phases does it require?
Open on GitHub → Explain another repo

← lakr233 on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.