The vphone‑cli project enables users to boot a virtual iPhone on Apple Silicon Macs by using Apple’s Virtualization.framework. According to the source text, the required host environment is an Apple Silicon Mac running macOS 15+ (Sequoia) with Xcode and the iOS SDK installed, and with SIP/AMFI relaxed to allow private PV=3 entitlements for unsigned binaries. The repository lists the dependencies that must be installed via Homebrew: [email protected], aria2, wget, gnu‑tar, openssl@3, ldid‑procursus, sshpass, keystone, cmake, libusb, ipsw, zstd, and the custom tap vphone‑cli. After installing these, the setup script ./scripts/setup_tools.sh installs build tools, creates a Python virtual environment, and pulls submodules. The build script ./scripts/build.sh then compiles and signs the vphone‑cli binary, bundles the .app, and cross‑compiles the guest daemon vphoned. Once built, a virtual iPhone can be created end‑to‑end with a single command such as vphone-cli vm create myphone -V jb, which downloads an IPSW, patches the boot chain, performs a DFU restore, installs custom firmware, and boots the device. The same workflow can be executed manually: vphone-cli vm new creates an empty VM bundle, fw prepare downloads and merges IPSWs, fw patch applies a selected variant, vm launch --dfu boots into DFU mode, restore fetches SHSH and restores the firmware, vm stop ends the DFU boot, cfw install installs the custom firmware, and a final vm launch starts the device. Five patch variants are defined, differing in the number of patches applied to the boot chain and the phases of custom firmware installation. The “less” variant applies 4 patches in 2 phases and leaves iOS mitigations enabled; “regular” uses 42 patches and 10 phases to bypass AMFI, SSV, Img4, and TXM; “dev” adds a TXM entitlement/debug bypass with 53 patches and 12 phases; “jb” provides a full jailbreak with 113 patches and 14 phases, automatically installing Sileo and TrollStore on first boot; and “exp” extends the jailbreak with additional anti‑VM‑detection research patches (141 patches, 18 phases). SSH access varies by variant: the jailbreak (jb/exp) permits ssh -p 22222 mobile@<vm-ip> with the password alpine, while regular and dev variants allow ssh -p 22222 root@<vm-ip>. A VNC server is available at vnc://<vm-ip>:5901. All VM‑related data resides under ~/.vphone/ by default, with subdirectories for VM bundles, cached IPSWs, APFS seal‑volume tools, Debian packages used by the custom firmware, and the Python virtual environment. These locations can be overridden with environment variables such as $VPHONE_ROOT, $VPHONE_LIBRARY_ROOT, and $VPHONE_VENV_DIR, where per‑item overrides take precedence over the root override, which in turn overrides the default. To run the tool, SIP can be fully disabled and the boot‑arg amfi_get_out_of_my_way=1 -v set, or SIP can be kept enabled while using the provided vphone-amfidont binary to allowlist the vphone‑cli executable. The source includes a compatibility table showing tested host/iPhone/CloudOS pairs (e.g., Mac16,11 with iPhone 17,3 running various iOS and CloudOS builds). Limitations noted are that virtualization cannot be nested; the host must be a non‑nested macOS 15+ system. If the boot process stalls on “Press home to continue,” users should connect via VNC and perform a two‑finger click to simulate the home button. System apps may fail to install if the region is set to Japan or the EU during iOS setup due to regulatory checks the VM cannot satisfy; selecting a region such as the United States avoids this issue. App crashes with EXC_GUARD / GUARD_TYPE_MACH_PORT can be addressed by re‑patching with vphone-cli fw patch <name> --variant <v> --force-exc-guard and then repeating the restore and install steps. A known bug in ldid‑procursus (up to version 2.1.5‑procursus7) causes infinite loops when processing entitlements containing an integer value of zero; the fix is to rebuild from source with brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus after hung
