vphone-cli
CLI ToolLakr233/vphone-cli
Boot virtual iPhones on Apple Silicon using Virtualization.framework.
Overview
Command-line tool that creates, patches and launches virtual iPhones on Apple Silicon Macs. It automates IPSW download, DFU restore, and custom firmware installation, with variants ranging from patchless to full jailbreak. Built on Apple's Virtualization.framework and the PCC research VM infrastructure.
README Preview
🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English\n\n# vphone-cli\n\nBoot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.\n\n\n\n## Prerequisites\n\n**Host:**\n\n- Apple Silicon\n- macOS 15+ (Sequoia)\n- Xcode + iOS SDK (cross-compiles the guest daemon)\n- [SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary](#sipamfi-relaxation)\n\n**Dependencies:**\n\n```bash\nbrew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd\n```\n\n## Install\n\n```bash\nbrew install zqxwce/tap/vphone-cli\n```\n\n## Build\n\n```bash\ngit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git\n\n./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv\n./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned\n\ncd .build/vphone-cli.app/Contents/MacOS/\nvphone-cli --help\n```\n\n## Quick Start\n\nOne command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):\n\n```bash\nvphone-cli vm create myphone -V jb # -V / --variant\n\nvphone-cli vm launch myphone\n```\n\n## Commands\n\n`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.\n\n### Manage\n\n```bash\nvphone-cli vm list # list VMs (--json for scripting)\nvphone-cli vm info myphone # show one VM\nvphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options)\nvphone-cli vm config myphone --cpu 8 --memory 8192\nvphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity\nvphone-cli vm export myphone --out myphone.tzst # zstd fast by default (--max = xz -9); --out may be a dir (auto-names .tzst/.txz); skips restore dir + staging files\nvphone-cli vm import myphone.tzst --name restored\nvphone-cli vm rename myphone iphone16\nvphone-cli vm d
FAQ (5)
TroubleshootingHow to fix the VPhone Clone option not working on macOS 27?
Upgrade to **VPhone.bundle 2.9.0**; the fix is in commit 7d22444d. On macOS 27, /dev device numbers can exceed Int32.max, causing Clone's pre-copy check to crash when scanning processes that have /dev/null, the disk image, SEPStorage, or nvram.bin open. This also breaks vphone-cli vm clone, snapshots, and revert. After installing the 2.9.0 bundle, update each existing virtual machine's **Core Bundle** setting to **2.9.0**, then use **Clone…**, snapshot, or revert again.
TroubleshootingHow do I fix "IPA: archive expands beyond one GiB" when installing a large IPA with apps.install?
Upgrade to a build containing **icli 0.7.18 or newer**; vphone-cli main uses it from commit 9c9446a0. In that version the extraction limit was raised from **1 GiB to 8 GiB**, and the maximum entry count was raised from **50,000 to 400,000**. After upgrading, retry:
vphone-launchpad-cli guest rpc <machine> apps.install '{"path":"<guest path to .ipa>"}'A 1.89 GB IPA with 96,764 entries then extracts successfully. There is no environment variable, plist, or runtime setting to change the limit in older releases; the 1 GiB cap was a compile-time constant. If you remain on vphone-launchpad 2.8.0/icli 0.7.17, you must upgrade or build a custom icli with a larger kArchiveByteLimit. New refusals include the actual size, e.g. IPA: archive expands to 8.79 GiB, over the 8 GiB limit.
TroubleshootingHow to fix "Set up and slim system failed" error "service group(s) accounts need the trimmed service list" on iOS 18 in VPhone Launchpad?
This happens because Launchpad 2.9.5 always passes --accounts-off when "Turn off unneeded services" is enabled (the default), but the trimmed service list only exists in vphoned for iOS 26/27. On iOS < 26 (e.g., iOS 18.6.2) the setup step fails and retrying repeats the same failing arguments. Workaround: when creating the machine, open Advanced Options → Services and Apps and turn OFF "Turn off unneeded services". Launchpad then passes --service-profile none instead of --accounts-off, and creation succeeds. On iOS < 26 this loses nothing since the trimmed service list doesn't exist for those versions anyway. A proper fix would make Launchpad only pass --accounts-off for iOS majors in trimmedServiceProfileMajors ([26, 27]).
TroubleshootingWhy does Bark show 'Unknown Status' and fail to obtain an APNs device token in VPhone?
This is expected. VPhone does not support obtaining an Apple APNs device token or receiving APNs-delivered remote notifications because APNs registration requires Apple device attestation and exchange of a private secure token, which the virtual environment cannot provide. There is no planned fix. Enabling notifications, having the aps-environment: production entitlement, or confirming that com.apple.apsd is running will not produce a usable token. As a workaround, implement a custom daemon that communicates with Bulletin Board to provide equivalent notification functionality.
TroubleshootingHow to fix SSH (OpenSSH) not working on roothide bootstrap in vphone?
In vphone 2.1.0 with roothide bootstrap, installing only openssh via the irisin package manager is not enough — the rootfs symlink is still missing inside /private/var/containers/Bundle/Application/.jbroot-*. Fix: also install the base package from irisin. After both openssh and base are installed, SSH works with no additional steps required.