Lakr233 / vphone-cli

查看原文 / View Original 编辑 / Edit

Lakr233 / vphone-cli

vphone-cli allows you to boot a virtual iPhone via Apple’s Virtualization.framework using PCC research VM infrastructure.

vphone-cli 允许你利用 Apple 的 Virtualization.framework 以及 PCC 研究用虚拟机基础设施来启动一个虚拟 iPhone。

Prerequisites / 前置条件

  • Host: Apple Silicon macOS 15+ (Sequoia)
  • Host: Apple Silicon macOS 15+ (Sequoia)
  • Xcode + iOS SDK: (cross-compiles the guest daemon)
  • Xcode + iOS SDK:（用于交叉编译客户机守护进程）
  • SIP/AMFI relaxation: to allow private PV=3 entitlements with unsigned-binary
  • SIP/AMFI 放宽限制： 以允许带有未签名二进制文件的私有 PV=3 授权。

Dependencies: brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

Install / 安装

brew install zqxwce/tap/vphone-cli

Build / 构建

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv
./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

Quick Start / 快速开始

One command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot): 一条命令即可完成虚拟机的端到端创建（下载 → 打补丁 → DFU 恢复 → 安装 CFW → 首次启动）：

vphone-cli vm create myphone -V jb # -V / --variant
vphone-cli vm launch myphone

Commands / 命令

vphone-cli vm create runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage. vphone-cli vm create 会运行整个流程；以下独立步骤允许你手动操作或重新运行某个阶段。

Manage / 管理

  • vphone-cli vm list # list VMs (—json for scripting) / 列出虚拟机（使用 —json 可用于脚本）
  • vphone-cli vm info myphone # show one VM / 显示单个虚拟机信息
  • vphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options) / 创建空包（可配置 CPU/内存/磁盘）
  • vphone-cli vm config myphone --cpu 8 --memory 8192
  • vphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity / 快速 APFS 克隆，生成新的设备标识
  • vphone-cli vm export myphone --out myphone.tzst # zstd fast by default; skips restore dir + staging files / 默认使用 zstd 快速导出；跳过恢复目录和暂存文件
  • vphone-cli vm import myphone.tzst --name restored
  • vphone-cli vm rename myphone iphone16
  • vphone-cli vm delete iphone16

Build a VM manually / 手动构建虚拟机

(what vm create automates / vm create 自动化的内容)

  1. vphone-cli vm new myphone # empty bundle / 空包
  2. vphone-cli fw prepare myphone --iphone-version 26.1 # download + merge IPSWs / 下载并合并 IPSW
  3. vphone-cli fw patch myphone --variant jb # patch the boot chain / 给引导链打补丁
  4. vphone-cli vm launch myphone --dfu & # boot into DFU (background) / 进入 DFU 模式（后台）
  5. vphone-cli restore myphone --get-shsh # fetch SHSH / 获取 SHSH
  6. vphone-cli restore myphone # DFU restore / DFU 恢复
  7. vphone-cli vm stop myphone # stop the DFU boot / 停止 DFU 引导
  8. vphone-cli cfw install myphone --variant jb # install CFW (host-mount; asks for sudo) / 安装 CFW（主机挂载；需要 sudo）
  9. vphone-cli vm launch myphone # first boot / 首次启动

Firmware Variants / 固件变体

Five patch variants with increasing security bypass — pass one to --variant: 五种补丁变体，安全绕过程度递增 — 将其传递给 --variant 参数：

VariantBoot ChainCFWNotes
less4 patches2 phasesPatchless — keeps iOS mitigations enabled / 无补丁 — 保持 iOS 防护机制开启
regular42 patches10 phasesAMFI/SSV/Img4/TXM bypass
dev53 patches12 phases+ TXM entitlement/debug bypass
jb113 patches14 phases+ full jailbreak (Sileo, TrollStore auto-install) / + 完整越狱（自动安装 Sileo, TrollStore）
exp141 patches18 phasesJB superset + anti-VM-detection research patches / 越狱超集 + 反虚拟机检测研究补丁

Running & Connecting / 运行与连接

  • SSH (jailbreak): ssh -p 22222 mobile@<vm-ip> (password alpine)
  • SSH (regular/dev): ssh -p 22222 root@<vm-ip>
  • VNC: vnc://<vm-ip>:5901

Locations / 文件路径

Everything vphone-cli creates lives under ~/.vphone/ — kept outside the repo and the .app so the signed bundle stays portable. vphone-cli 创建的所有内容都位于 ~/.vphone/ 下 — 保持在仓库和 .app 之外，以确保已签名的包保持可移植性。

  • ~/.vphone/VMs/: VM bundles (the library) / 虚拟机包（库文件）
  • ~/.vphone/ipsws/: Downloaded iPhone + cloudOS IPSWs / 已下载的 iPhone 和 cloudOS IPSW
  • ~/.vphone/tools/: Cached APFS seal-volume artifacts / 缓存的 APFS 密封卷制品
  • ~/.vphone/debs/: Cached .deb packages for CFW / 用于 CFW 的缓存 .deb 包
  • ~/.vphone/venv/: Auto-provisioned Python environment / 自动配置的 Python 环境

SIP/AMFI Relaxation / SIP/AMFI 放宽限制

Option A (Most permissive): Fully disable SIP, then disable AMFI via boot-arg. 选项 A（最宽松）： 完全禁用 SIP，然后通过 boot-arg 禁用 AMFI。 In Recovery (long-press power → Terminal): 在恢复模式下（长按电源键 → 终端）：

csrutil disable
csrutil allow-research-guests enable

Then reboot into macOS and set the AMFI boot-arg: 重启进入 macOS 并设置 AMFI boot-arg： sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

Option B: Keep SIP on (debug-only relaxed), then allowlist the binary with amfidont. 选项 B： 保持 SIP 开启（仅放宽调试限制），然后使用 amfidont 将二进制文件加入白名单。 In Recovery: 在恢复模式下：

csrutil enable --without debug
csrutil allow-research-guests enable

Then reboot into macOS and: vphone-amfidont

FAQ / 常见问题

  • zsh: killed ./vphone-cli: AMFI/debug restrictions aren’t bypassed; see Prerequisites. AMFI/调试限制未被绕过；请参阅“前置条件”。
  • Virtualization is not available on this hardware: Your Mac is itself a VM; PV=3 guest boot can’t nest. Use a non-nested macOS 15+ host. 你的 Mac 本身就是一台虚拟机；PV=3 客户机引导无法嵌套。请使用非嵌套的 macOS 15+ 主机。
  • Stuck on “Press home to continue”: Connect via VNC and right-click (two-finger click) to simulate the home button. 卡在“按下主屏幕按钮以继续”：通过 VNC 连接并右键点击（双指点击）以模拟主屏幕按钮。
← 返回新闻列表 / Back to news list