vphone-cli Documentation

File: README.md Copy Chapter

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

Boot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.

Prerequisites Copy Chapter

Host:

• Apple Silicon
• macOS 15+ (Sequoia)
• Xcode + iOS SDK (cross-compiles the guest daemon)
• SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary

Dependencies:

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

Install Copy Chapter

brew install zqxwce/tap/vphone-cli

Build Copy Chapter

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 Copy Chapter

One command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):

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

vphone-cli vm launch myphone

Commands Copy Chapter

vphone-cli vm create runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.

Manage Copy Section

vphone-cli vm list                         # list VMs (--json for scripting)
vphone-cli vm info myphone                  # show one VM
vphone-cli vm new myphone                   # create an empty bundle (cpu/mem/disk options)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # fast APFS clone, fresh device identity
vphone-cli vm export myphone --out myphone.tzst   # zstd fast by default (--max = xz -9); --out may be a dir (auto-names <vm>.tzst/.txz); skips restore dir + staging files
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) Copy Section

vphone-cli vm new myphone                              # 1. empty bundle
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. download + merge IPSWs
vphone-cli fw patch myphone --variant jb                # 3. patch the boot chain

vphone-cli vm launch myphone --dfu &                    # 4. boot into DFU (background)
vphone-cli restore myphone --get-shsh                   #    fetch SHSH
vphone-cli restore myphone                              #    DFU restore
vphone-cli vm stop myphone                              #    stop the DFU boot

vphone-cli cfw install myphone --variant jb             # 5. install CFW (host-mount; asks for sudo)
vphone-cli vm launch myphone                            # 6. first boot

Update to a newer iOS by pointing fw prepare at an IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.

Firmware Variants Copy Chapter

Five patch variants with increasing security bypass — pass one to --variant:

See research/0_binary_patch_comparison.md for the per-component breakdown.

Running & Connecting Copy Chapter

• 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 Copy Chapter

Everything vphone-cli creates lives under ~/.vphone/ — kept outside the repo and the .app so the signed bundle stays portable. Redirect the whole tree with $VPHONE_ROOT:

Precedence: the per-item overrides ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) win over $VPHONE_ROOT, which wins over the ~/.vphone default. The ipsws/, tools/, and debs/ caches always sit directly under whichever root is active.

SIP/AMFI Relaxation Copy Chapter

Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).

In Recovery (long-press power → Terminal):

csrutil disable
csrutil allow-research-guests enable

Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # reboot after

Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont (leaves AMFI enabled system-wide).

In Recovery:

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

Then reboot into macOS and:

vphone-amfidont         # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds

Tested Environments Copy Chapter

FAQ Copy Chapter

zsh: killed ./vphone-cli — AMFI/debug restrictions aren't bypassed; see Prerequisites (amfi_get_out_of_my_way=1 or amfidont).

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.

Stuck on "Press home to continue" — connect via VNC and right-click (two-finger click) to simulate the home button.

System apps won't install — during iOS setup, don't pick Japan or the EU as your region (extra regulatory checks the VM can't satisfy); pick e.g. United States.

App crashes on launch with EXC_GUARD / GUARD_TYPE_MACH_PORT — re-patch with vphone-cli fw patch <name> --variant <v> --force-exc-guard, then re-restore/install (#291). Always on for iOS 18 bases.

Install a .ipa/.tipa — use the running VM's Install menu (drag-drop or file picker).

cfw install hangs re-signing a system binary (e.g. Campo), memory climbing unbounded — known bug in ldid-procursus up to 2.1.5-procursus7 (the current Homebrew stable): bytes(uint64_t) calls __builtin_clzll(0) with no zero-guard, which is undefined behavior, and on this build resolves to a 0-length that underflows an unsigned loop counter — ldid spins writing one byte at a time into a growing buffer instead of terminating. Triggered by any entitlements plist containing an integer value of exactly 0 (some real Apple system binaries have these). Fixed upstream but not yet in a tagged release; rebuild from source: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Kill the hung ldid process first (sudo kill -9 ) if you already hit it.

Automation Copy Chapter

vphone-cli exposes a host control socket (/vphone.sock) for programmatic control — screenshots, touch, swipes, hardware keys, clipboard — each action returning an inline screenshot for AI-driven E2E testing. See vphone-mcp for an MCP server wrapping it.

Acknowledgements Copy Chapter

• wh1te4ever/super-tart-vphone-writeup

File: docs/README_ja.md Copy Chapter

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

PCC リサーチ VM インフラストラクチャを使用し、Apple の Virtualization.framework 経由で仮想 iPhone を起動します。

前提条件 Copy Chapter

ホスト:

• Apple Silicon
• macOS 15+ (Sequoia)
• Xcode + iOS SDK（ゲストデーモンをクロスコンパイルするため）
• 未署名バイナリでプライベートな PV=3 エンタイトルメントを許可するための SIP/AMFI の緩和

依存関係:

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

インストール Copy Chapter

brew install zqxwce/tap/vphone-cli

ビルド Copy Chapter

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # 依存関係のインストール、ツールチェーンのサブモジュールのビルド、Python venv の作成
./scripts/build.sh            # vphone-cli のビルド + 署名、.app のバンドル、vphoned のクロスコンパイル

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

クイックスタート Copy Chapter

1 つのコマンドで VM をエンドツーエンドで作成します（ダウンロード → パッチ → DFU 復元 → CFW インストール → 初回起動）:

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

vphone-cli vm launch myphone

コマンド Copy Chapter

vphone-cli vm create はパイプライン全体を実行します。以下の個別ステップを使うと、手動で操作したり 1 つの段階を再実行したりできます。

管理 Copy Section

vphone-cli vm list                         # VM の一覧表示（スクリプト用に --json）
vphone-cli vm info myphone                  # 1 つの VM を表示
vphone-cli vm new myphone                   # 空のバンドルを作成（cpu/mem/disk オプション）
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   # zstd fast by default (--max = xz -9); --out がディレクトリなら <vm>.tzst/.txz を自動命名; 復元ディレクトリ + ステージングファイルをスキップ
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

VM を手動でビルドする（`vm create` が自動化する処理） Copy Section

vphone-cli vm new myphone                              # 1. 空のバンドル
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. IPSW のダウンロード + マージ
vphone-cli fw patch myphone --variant jb                # 3. ブートチェーンにパッチ適用

vphone-cli vm launch myphone --dfu &                    # 4. DFU で起動（バックグラウンド）
vphone-cli restore myphone --get-shsh                   #    SHSH を取得
vphone-cli restore myphone                              #    DFU 復元
vphone-cli vm stop myphone                              #    DFU 起動を停止

vphone-cli cfw install myphone --variant jb             # 5. CFW をインストール（ホストマウント; sudo を要求）
vphone-cli vm launch myphone                            # 6. 初回起動

新しい iOS に更新するには、fw prepare を IPSW に向けます: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw。

ファームウェアバリアント Copy Chapter

セキュリティバイパスの度合いが段階的に増す 5 つのパッチバリアント — いずれか 1 つを --variant に渡します:

コンポーネントごとの内訳については research/0_binary_patch_comparison.md を参照してください。

実行と接続 Copy Chapter

• SSH（脱獄）: ssh -p 22222 mobile@<vm-ip>（パスワード alpine）
• SSH（regular/dev）: ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

場所 Copy Chapter

vphone-cli が生成するものはすべて ~/.vphone/ 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと .app の外に保管されます。$VPHONE_ROOT でツリー全体をリダイレクトできます:

優先順位: 項目ごとの上書き（$VPHONE_LIBRARY_ROOT、$VPHONE_VENV_DIR）が $VPHONE_ROOT より優先され、$VPHONE_ROOT は ~/.vphone のデフォルトより優先されます。ipsws/、tools/、debs/ キャッシュは、常に現在有効なルートの直下に置かれます。

SIP/AMFI の緩和 Copy Chapter

オプション A — SIP を完全に無効化し、boot-arg で AMFI を無効化する（最も緩い）。

リカバリーモードで（電源ボタン長押し → ターミナル）:

csrutil disable
csrutil allow-research-guests enable

その後 macOS で再起動し、AMFI の boot-arg を設定します（有効化には SIP を完全に無効化する必要があります）:

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # 後で再起動

オプション B — SIP を有効なまま（デバッグのみ緩和）にし、amfidont でバイナリを許可リストに追加する（AMFI はシステム全体で有効なまま）。

リカバリーモードで:

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

その後 macOS で再起動し:

vphone-amfidont         # ローカルビルドの場合は .build/vphone-cli.app/Contents/Resources/vphone-amfidont

動作確認済み環境 Copy Chapter

FAQ Copy Chapter

zsh: killed ./vphone-cli — AMFI/デバッグ制限がバイパスされていません。前提条件 を参照してください（amfi_get_out_of_my_way=1 または amfidont）。

Virtualization is not available on this hardware — お使いの Mac 自体が VM です。PV=3 ゲスト起動はネストできません。ネストされていない macOS 15+ ホストを使用してください。

「Press home to continue」で止まる — VNC で接続し、右クリック（2 本指クリック）してホームボタンをシミュレートします。

システムアプリがインストールできない — iOS のセットアップ中に、地域として日本や EU を選ばないでください（VM が満たせない追加の規制チェックが入ります）。例えば United States を選択してください。

アプリが起動時に EXC_GUARD / GUARD_TYPE_MACH_PORT でクラッシュする — vphone-cli fw patch <name> --variant <v> --force-exc-guard で再パッチし、再度復元/インストールしてください（#291）。iOS 18 ベースでは常に有効です。

.ipa/.tipa をインストールする — 実行中の VM の Install メニューを使用します（ドラッグ&ドロップまたはファイルピッカー）。

自動化 Copy Chapter

vphone-cli はプログラムによる制御のためにホスト制御ソケット（/vphone.sock）を公開します — スクリーンショット、タッチ、スワイプ、ハードウェアキー、クリップボード — 各アクションは AI 駆動の E2E テスト用にインラインのスクリーンショットを返します。それをラップする MCP サーバーについては vphone-mcp を参照してください。

謝辞 Copy Chapter

• wh1te4ever/super-tart-vphone-writeup

File: docs/README_ko.md Copy Chapter

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

PCC 리서치 VM 인프라를 사용하여 Apple의 Virtualization.framework로 가상 iPhone을 부팅합니다.

사전 요구 사항 Copy Chapter

호스트:

• Apple Silicon
• macOS 15+ (Sequoia)
• Xcode + iOS SDK (게스트 데몬 크로스 컴파일용)
• 서명되지 않은 바이너리로 private PV=3 권한을 허용하기 위한 SIP/AMFI 완화

의존성:

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

설치 Copy Chapter

brew install zqxwce/tap/vphone-cli

빌드 Copy Chapter

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # 의존성 설치, 툴체인 서브모듈 빌드, Python venv 생성
./scripts/build.sh            # vphone-cli 빌드 및 서명, .app 번들 생성, vphoned 크로스 컴파일

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

빠른 시작 Copy Chapter

하나의 명령으로 VM을 처음부터 끝까지 생성합니다 (다운로드 → 패치 → DFU 복원 → CFW 설치 → 첫 부팅):

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

vphone-cli vm launch myphone

명령어 Copy Chapter

vphone-cli vm create는 전체 파이프라인을 실행합니다; 아래 개별 단계들을 사용하면 수동으로 진행하거나 한 단계만 다시 실행할 수 있습니다.

관리 Copy Section

vphone-cli vm list                         # VM 목록 표시 (스크립팅용 --json)
vphone-cli vm info myphone                  # VM 하나 표시
vphone-cli vm new myphone                   # 빈 번들 생성 (cpu/mem/disk 옵션)
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   # zstd fast by default (--max = xz -9); --out 이 디렉토리면 <vm>.tzst/.txz 자동 명명; restore 디렉토리 + 스테이징 파일 건너뜀
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

VM 수동 빌드 (`vm create`가 자동화하는 작업) Copy Section

vphone-cli vm new myphone                              # 1. 빈 번들
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. IPSW 다운로드 + 병합
vphone-cli fw patch myphone --variant jb                # 3. 부트 체인 패치

vphone-cli vm launch myphone --dfu &                    # 4. DFU로 부팅 (백그라운드)
vphone-cli restore myphone --get-shsh                   #    SHSH 가져오기
vphone-cli restore myphone                              #    DFU 복원
vphone-cli vm stop myphone                              #    DFU 부팅 중지

vphone-cli cfw install myphone --variant jb             # 5. CFW 설치 (호스트 마운트; sudo 요청)
vphone-cli vm launch myphone                            # 6. 첫 부팅

최신 iOS로 업데이트하려면 fw prepare를 IPSW로 지정하세요: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.

펌웨어 변형 Copy Chapter

보안 우회 수준이 점점 강해지는 5가지 패치 변형이 있습니다 — 하나를 --variant에 전달하세요:

컴포넌트별 상세 분류는 research/0_binary_patch_comparison.md를 참조하세요.

실행 및 연결 Copy Chapter

• SSH (탈옥): ssh -p 22222 mobile@<vm-ip> (비밀번호 alpine)
• SSH (regular/dev): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

위치 Copy Chapter

vphone-cli가 생성하는 모든 것은 ~/.vphone/ 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 .app 외부에 보관됩니다. $VPHONE_ROOT로 전체 트리를 리디렉션할 수 있습니다:

우선순위: 항목별 재정의($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR)가 $VPHONE_ROOT보다 우선하고, $VPHONE_ROOT는 ~/.vphone 기본값보다 우선합니다. ipsws/, tools/, debs/ 캐시는 항상 현재 활성 루트 바로 아래에 위치합니다.

SIP/AMFI 완화 Copy Chapter

방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대).

복구 모드에서 (전원 버튼 길게 누르기 → 터미널):

csrutil disable
csrutil allow-research-guests enable

그런 다음 macOS로 재부팅하고 AMFI boot-arg를 설정합니다 (적용되려면 SIP가 완전히 꺼져 있어야 합니다):

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # 이후 재부팅

방법 B — SIP 유지 (디버그만 완화), 그런 다음 amfidont로 바이너리를 허용 목록에 추가 (AMFI는 시스템 전체에서 활성 상태 유지).

복구 모드에서:

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

그런 다음 macOS로 재부팅하고:

vphone-amfidont         # 로컬 빌드의 경우 .build/vphone-cli.app/Contents/Resources/vphone-amfidont

테스트 환경 Copy Chapter

FAQ Copy Chapter

zsh: killed ./vphone-cli — AMFI/디버그 제한이 우회되지 않았습니다; 사전 요구 사항을 참조하세요 (amfi_get_out_of_my_way=1 또는 amfidont).

Virtualization is not available on this hardware — Mac 자체가 VM입니다; PV=3 게스트 부팅은 중첩할 수 없습니다. 중첩되지 않은 macOS 15+ 호스트를 사용하세요.

"Press home to continue"에서 멈춤 — VNC로 접속하여 우클릭(두 손가락 클릭)으로 홈 버튼을 시뮬레이션하세요.

시스템 앱이 설치되지 않음 — iOS 초기 설정 시 지역으로 일본이나 EU를 선택하지 마세요 (VM이 충족할 수 없는 추가 규제 검사가 있습니다); 예를 들어 United States를 선택하세요.

앱이 실행 시 EXC_GUARD / GUARD_TYPE_MACH_PORT로 충돌 — vphone-cli fw patch <name> --variant <v> --force-exc-guard로 다시 패치한 다음, 다시 복원/설치하세요 (#291). iOS 18 베이스에서는 항상 켜져 있습니다.

.ipa/.tipa 설치 — 실행 중인 VM의 Install 메뉴를 사용하세요 (드래그 앤 드롭 또는 파일 선택기).

자동화 Copy Chapter

vphone-cli는 프로그래밍 방식 제어를 위한 호스트 제어 소켓(/vphone.sock)을 노출합니다 — 스크린샷, 터치, 스와이프, 하드웨어 키, 클립보드 — 각 동작은 AI 주도 E2E 테스트를 위해 인라인 스크린샷을 반환합니다. 이를 감싸는 MCP 서버는 vphone-mcp를 참조하세요.

감사의 말 Copy Chapter

• wh1te4ever/super-tart-vphone-writeup

File: docs/README_zh.md Copy Chapter

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

使用 PCC 研究虚拟机基础设施，通过 Apple 的 Virtualization.framework 启动一台虚拟 iPhone。

前置条件 Copy Chapter

宿主机：

• Apple Silicon
• 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

安装 Copy Chapter

brew install zqxwce/tap/vphone-cli

构建 Copy Chapter

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # 安装依赖、构建工具链子模块、创建 Python venv
./scripts/build.sh            # 构建并签名 vphone-cli、打包 .app、交叉编译 vphoned

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

快速开始 Copy Chapter

一条命令即可端到端创建一台虚拟机（下载 → 打补丁 → DFU 恢复 → CFW 安装 → 首次启动）：

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

vphone-cli vm launch myphone

命令 Copy Chapter

vphone-cli vm create 会运行整个流水线；下面的各个步骤让你可以手动驱动它，或重新运行某一个阶段。

管理 Copy Section

vphone-cli vm list                         # 列出虚拟机（--json 用于脚本）
vphone-cli vm info myphone                  # 显示某台虚拟机
vphone-cli vm new myphone                   # 创建一个空 bundle（cpu/内存/磁盘选项）
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   # zstd fast by default（--max = xz -9）；--out 为目录时自动命名 <vm>.tzst/.txz；跳过 restore 目录 + 暂存文件
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

手动构建虚拟机（`vm create` 自动化的流程） Copy Section

vphone-cli vm new myphone                              # 1. 空 bundle
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. 下载并合并 IPSW
vphone-cli fw patch myphone --variant jb                # 3. 给引导链打补丁

vphone-cli vm launch myphone --dfu &                    # 4. 启动进入 DFU（后台）
vphone-cli restore myphone --get-shsh                   #    获取 SHSH
vphone-cli restore myphone                              #    DFU 恢复
vphone-cli vm stop myphone                              #    停止 DFU 引导

vphone-cli cfw install myphone --variant jb             # 5. 安装 CFW（宿主机挂载；会请求 sudo）
vphone-cli vm launch myphone                            # 6. 首次启动

要升级到更新的 iOS，把 fw prepare 指向一个 IPSW：--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw。

固件变体 Copy Chapter

五种补丁变体，安全绕过程度递增——将其中之一传给 --variant：

各组件的详细拆解见 research/0_binary_patch_comparison.md。

运行与连接 Copy Chapter

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

位置 Copy Chapter

vphone-cli 创建的所有内容都位于 ~/.vphone/ 下——保存在仓库和 .app 之外，以便签名后的包保持可移植。可用 $VPHONE_ROOT 重定向整个目录树：

优先级：单项覆盖（$VPHONE_LIBRARY_ROOT、$VPHONE_VENV_DIR）优先于 $VPHONE_ROOT，$VPHONE_ROOT 优先于 ~/.vphone 默认值。ipsws/、tools/ 和 debs/ 缓存始终位于当前生效的根目录之下。

放宽 SIP/AMFI Copy Chapter

方案 A——完全禁用 SIP，然后通过 boot-arg 禁用 AMFI（最宽松）。

在恢复模式下（长按电源键 → 终端）：

csrutil disable
csrutil allow-research-guests enable

然后重启进入 macOS 并设置 AMFI boot-arg（需要 SIP 完全关闭才能生效）：

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # 之后重启

方案 B——保持 SIP 开启（仅放宽 debug），然后用 amfidont 将二进制加入白名单（AMFI 在系统范围内保持启用）。

在恢复模式下：

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

然后重启进入 macOS 并执行：

vphone-amfidont         # 本地构建见 .build/vphone-cli.app/Contents/Resources/vphone-amfidont

测试环境 Copy Chapter

常见问题 Copy Chapter

zsh: killed ./vphone-cli —— AMFI/debug 限制未被绕过；见前置条件（amfi_get_out_of_my_way=1 或 amfidont）。

Virtualization is not available on this hardware —— 你的 Mac 本身就是一台虚拟机；PV=3 客户机启动无法嵌套。请使用非嵌套的 macOS 15+ 宿主机。

卡在 “Press home to continue” —— 通过 VNC 连接，然后右键点击（双指点击）来模拟 home 键。

系统应用无法安装 —— 在 iOS 设置过程中，不要选择日本或欧盟作为你的地区（会有额外的监管检查，虚拟机无法满足）；请选择例如美国。

应用启动时崩溃并报 EXC_GUARD / GUARD_TYPE_MACH_PORT —— 用 vphone-cli fw patch <name> --variant <v> --force-exc-guard 重新打补丁，然后重新恢复/安装（#291）。对于 iOS 18 基础版本始终启用。

安装 .ipa/.tipa —— 使用运行中虚拟机的 Install 菜单（拖放或文件选择器）。

自动化 Copy Chapter

vphone-cli 暴露了一个宿主控制套接字（/vphone.sock）用于程序化控制——截图、触控、滑动、硬件按键、剪贴板——每个动作都会返回一张内联截图，用于 AI 驱动的端到端测试。包装它的 MCP 服务器见 vphone-mcp。

致谢 Copy Chapter

• wh1te4ever/super-tart-vphone-writeup

File: research/kernel_patch_jb/runtime_verification/README.md Copy Chapter

JB Runtime Verification Runbook

This folder contains runtime + IDA verification artifacts for jailbreak kernel patches.

Quick Commands Copy Chapter

Run runtime verification against a kernel file:

make jb_verify_runtime KERNEL_PATH=/path/to/kernelcache.research.vphone600 WORKERS=8

Refresh patch-doc tails from latest reports:

make jb_update_runtime_docs

Core Artifacts Copy Chapter

• runtime_verification_report.json
  • Source of truth for runtime patch hit/no-hit status.
  • Includes scheduler coverage (methods_scheduled, doc_methods_unscheduled).
• runtime_verification_summary.md
  • Human-readable summary.
• runtime_patch_points.json
  • Flat list of runtime patch points used for IDA join.
• ida_runtime_patch_points.json
  • Runtime points enriched with IDA function/disassembly context.

Current Baseline (2026-03-05) Copy Chapter

• Kernel: /Users/qaq/Documents/Firmwares/PCC-CloudOS-26.3-23D128/kernelcache.research.vphone600
• Runtime result: 22 hit / 2 nohit / 0 error
• Default KernelJBPatcher.find_all() scheduled methods: 7
• Doc methods unscheduled: 17
• No-hit methods:
  • patch_post_validation_additional
  • patch_syscallmask_apply_to_proc

Regression Gate Copy Chapter

Treat verification as regressed if any of the following occurs:

• status=error appears in runtime_verification_report.json.
• A previously hit method becomes nohit without explicit scheduler/matcher change.
• methods_scheduled_count changes unexpectedly from intended plan.
• doc_methods_unscheduled changes unexpectedly.

File: scripts/tweakloader/README.md Copy Chapter

Lean TweakLoader

Purpose

• Provide the /var/jb/usr/lib/TweakLoader.dylib component expected by the
  vphone JB basebin runtime (systemhook.dylib).
• Load user tweak dylibs from
  /var/jb/Library/MobileSubstrate/DynamicLibraries into matching processes.

Current behavior

• Enumerates substrate-style .plist files in the tweak directory.
• Supports:
  • Filter.Bundles
  • Filter.Executables
• dlopens the corresponding .dylib when the current process matches.

Logging

• Writes to /var/jb/var/mobile/Library/TweakLoader/tweakloader.log.