vphone-cli：借助Apple虚拟化框架，在Apple Silicon Mac上运行虚拟iPhone

vphone-cli 是面向PCC研究的虚拟机基础设施工具，依托Apple官方Virtualization.framework，可在Apple Silicon Mac上启动iPhone虚拟机，支持固件打补丁、CFW安装，最高可直接构建预装Sileo、TrollStore的越狱iOS虚拟机。

• GitHub：https://github.com/Lakr233/vphone-cli
• GitHub：https://github.com/34306/vphone-aio
• GitHub：https://github.com/34306/vphone-web

前置条件

宿主机硬性要求

• Apple Silicon芯片Mac
• macOS 15（Sequoia）及以上
• 安装Xcode + iOS SDK，用于交叉编译访客端守护进程
• 需要放宽SIP/AMFI，授权未签名二进制使用私有PV=3权限

依赖安装

brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

安装与源码构建

Homebrew一键安装：

brew install zqxwce/tap/vphone-cli

源码编译：

git clone --recurse-submodules [https://github.com/Lakr233/vphone-cli.git](https://github.com/Lakr233/vphone-cli.git)
./scripts/setup_tools.sh
./scripts/build.sh
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

快速上手

一条命令完成全流程：下载IPSW、固件打补丁、DFU恢复、CFW部署、首次开机

vphone-cli vm create myphone -V jb
vphone-cli vm launch myphone

核心管理命令

vphone-cli vm list                         # 列出全部虚拟机
vphone-cli vm info myphone                  # 查看虚拟机详情
vphone-cli vm new myphone                   # 创建空虚拟机容器
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # APFS快速克隆，全新设备标识
vphone-cli vm export myphone --out myphone.tzst
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

手动分步构建虚拟机（vm create自动化的底层流程）

vphone-cli vm new myphone
vphone-cli fw prepare myphone --iphone-version 26.1
vphone-cli fw patch myphone --variant jb
vphone-cli vm launch myphone --dfu &
vphone-cli restore myphone --get-shsh
vphone-cli restore myphone
vphone-cli vm stop myphone
vphone-cli cfw install myphone --variant jb
vphone-cli vm launch myphone

固件补丁变体（–variant）

访问虚拟机

• SSH（jb越狱版）：ssh -p 22222 mobile@<vm-ip> 密码 alpine
• SSH（regular/dev）：ssh -p 22222 root@<vm-ip>
• VNC：vnc://<vm-ip>:5901

文件目录

默认所有数据存放于~/.vphone/，支持环境变量自定义路径

• ~/.vphone/VMs/：虚拟机实例
• ~/.vphone/ipsws/：IPSW固件缓存，多虚拟机复用
• ~/.vphone/tools/：APFS制品缓存
• ~/.vphone/debs/：deb安装包缓存
• ~/.vphone/venv/：内置Python虚拟环境

SIP / AMFI 两种放宽方案

方案A（完全关闭SIP，最宽松）

# 恢复终端
csrutil disable
csrutil allow-research-guests enable
# macOS内设置启动参数
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

方案B（保留SIP，仅debug放宽，全局AMFI启用）

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

自动化能力

vphone-cli提供宿主机控制套接字vphone.sock，可程序化执行截图、触控滑动、按键、剪贴板操作，每次指令返回截图，适合AI端到端测试；配套MCP服务vphone-mcp。

常见问题

1. zsh: killed：AMFI/debug限制未正确放行，检查boot-args或amfidont
2. Virtualization硬件不可用：Mac嵌套虚拟机，PV=3无法嵌套虚拟化，必须裸金属Apple Silicon Mac
3. 卡在Press home to continue：VNC连接，双指右键模拟Home键
4. EXC_GUARD崩溃：使用--force-exc-guard重新打补丁

提示：该项目仅用于安全研究，在非授权设备上越狱、虚拟化iOS存在法律与平台协议风险。