Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs: simplify README and document bootstrap setup

Lakrfc78651607b0
diff --git a/Documents/README_ja.md b/Documents/README_ja.md
index ffcd99a6..cc19e768 100644
--- a/Documents/README_ja.md
+++ b/Documents/README_ja.md
@@ -1,49 +1,77 @@
-<div align="right"><a href="README_zh.md">中文</a> · <strong>日本語</strong> · <a href="README_ko.md">한국어</a></div>
+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <strong>日本語</strong> · <a href="README_ko.md">한국어</a></div>
# vphone-cli
-Apple の Virtualization.framework と PCC 研究用 VM 基盤を使って、仮想 iPhone を起動します。
+> [!WARNING]
+> バージョン 2.0 は開発中です。安定版が必要な場合は [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14) を使用してください。
-![macOS 上の仮想 iPhone](demo.jpeg)
+Apple Silicon Mac 上で仮想 iPhone を作成・実行します。vphone-cli は Apple の Virtualization.framework と PCC 研究用 VM 基盤を使用します。
-公開されているファームウェア構成は **JB のみ**です。必要なシステムパッチとホスト制御用の vphoned を導入します。ゲストのユーザー環境はそのままにし、パッケージマネージャー、SSH、VNC、初回起動時の bootstrap はインストールしません。
+![macOS 上で動作する仮想 iPhone](demo.jpeg)
-## クイックスタート
+バージョン 2.0 では、1.0 の負担が大きく複雑なホスト設定を大幅に減らし、カスタムファームウェアに必要なシステム修正を整理しました。基本の流れが安定してきたため、構成は **JB の 1 種類**に絞っています。自己完結した `VPhone.bundle` の CLI から、ファームウェアのダウンロード、インストール、起動まで行えます。
-Apple Silicon、macOS 15 以降、および PV=3 研究用 VM と `vphone-vm` の権限を許可する[ホスト設定](Guides/host-setup.md)が必要です。
+現時点で推奨するホスト設定は、macOS 復旧環境で `csrutil enable --without debug` と `csrutil allow-research-guests enable` を実行する方法です。SIP は有効のまま、デバッグの制限を緩和します。AMFI に VM バイナリを許可させるには root 権限が必要です。手順は[ホストの設定](Guides/host-setup.md)、仕組みは [amfi-allow の研究資料](https://github.com/Lakr233/amfi-allow)を参照してください。今後の `vphone-ui.app` ではセットアップを簡単にし、インストール時の修正を切り替えられるようにする予定です。
-**v2.0.0 の VM 互換性:**このリリースで起動できるのは、新しく作成された `schemaVersion=2` の VM だけです。旧バージョンで作成した VM は `vm create` で作り直してください。既存 VM の直接アップグレードには対応しません。
+## はじめに
+
+macOS 15 以降の Apple Silicon Mac、ソースからのビルドに使う Xcode、iPhone の復元 IPSW、互換性のある cloudOS IPSW が必要です。[ホストの設定](Guides/host-setup.md)で VM に必要なプライベート権限を許可し、[検証済みのファームウェアの組み合わせ](Guides/compatibility.md)を確認してください。macOS VM の中でゲストを動かすことはできません。
```sh
+git clone https://github.com/Lakr233/vphone-cli.git
+cd vphone-cli
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+export PATH="$PWD/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS:$PATH"
+
+vphone-cli host preflight
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
--cloudos-source /path/to/cloudOS.ipsw
-
vphone-cli vm launch myphone
```
-`vm create` は準備、JB パッチ、DFU 復元、CFW インストールを実行し、初回起動で vphoned に ping します。**確認用の起動は成功後に停止します。** 継続して使うには `vm launch` を実行してください。復元にはネットワーク接続、CFW インストールには管理者認証が必要です。
+`vm create` はゲストの準備と復元、JB システム変更の導入、`vphoned` の応答確認を行います。確認用の起動は完了後に停止します。使用するには `vm launch` で VM ウィンドウを開いてください。作成にはネットワーク接続、CFW のインストールには管理者権限が必要です。詳しくは[作成と起動のガイド](Guides/create-and-run.md)を参照してください。
-cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2(`23G90`)と 27.0(`24A435`)がロック画面に到達し、vphoned ping に応答しました。詳細は[互換性の記録](Guides/compatibility.md)を参照してください。
+2.x 版で起動できるのは `schemaVersion=2` 形式で作成された VM だけです。旧版の VM は作り直す必要があります。
-## インストールとビルド
+## カスタムファームウェアの Bootstrap
-Xcode は、将来 `vphone-workstation` に組み込む `VPhone.bundle` を生成します。実行時に Homebrew、Python、Xcode は不要です。bundle 内の CLI を直接実行できます。
+VM を起動したら、macOS のメニューバーで **Guest > Install Bootstrap…** を選び、環境のレイアウトを選択します。これによりゲスト内に Irisin がインストールされます。
-```sh
-.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
-```
+現時点では、Irisin で `coreutils`、`debianutils`、`dash` などの基本パッケージを 1 つずつインストールしてください。パッケージスクリプトのエラーで失敗した場合は、失敗した操作画面の左上にある **More** メニューから **Ignore Script Errors and Retry** を選びます。スクリプトは実行されますが、そのエラーを無視して続行します。環境が整ったら通常のインストールに戻せます。この初期設定は今後のリリースで改善する予定です。
-上の例では、`vphone-cli` をこのアプリ内のパスに置き換えられます。ソースからのビルドには、vphoned をコンパイルするための iPhoneOS SDK を含む Xcode が必要です。
+## 日常の操作
-```sh
-git clone https://github.com/Lakr233/vphone-cli.git
-cd vphone-cli
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-```
+VM ウィンドウにはアプリとファイルの閲覧、クリップボードと設定の操作、スクリーンショット、録画、診断機能があります。ローカルの自動化には `--api-listen 127.0.0.1:8765` を指定して起動します。詳しくは[ゲスト API](../Research/vphoned_http_api.md)を参照してください。
+
+| 操作 | コマンド |
+| --- | --- |
+| VM の一覧 | `vphone-cli vm list` |
+| VM の情報 | `vphone-cli vm info myphone` |
+| VM ウィンドウの起動 | `vphone-cli vm launch myphone` |
+| VM の停止 | `vphone-cli vm stop myphone` |
+| バックアップの書き出し | `vphone-cli vm export myphone --out myphone.tzst` |
+| バックアップの読み込み | `vphone-cli vm import myphone.tzst --name restored` |
+
+VM は標準で `~/.vphone/` に保存されます。その他のコマンドは `vphone-cli <group> --help` で確認できます。
+
+## 構成
+
+`vphone-cli` はファームウェアの準備、VM の復元と管理を担当します。bundle 内の `vphone-vm` がゲストを実行し、macOS ウィンドウを管理します。ゲスト内の `vphoned` はウィンドウ操作と、任意で公開する HTTP・WebSocket API を提供します。Xcode の `VPhone` scheme は自己完結した `VPhone.bundle` をビルドして検証します。
+
+## リポジトリ案内
+
+| パス | 内容 |
+| --- | --- |
+| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI、VM プロセス、ファームウェアパッチ、復元処理 |
+| [`VPhoneKit/`](../VPhoneKit/) | ホスト側の共通ライブラリと API クライアント |
+| [`VPhoneDaemon/`](../VPhoneDaemon/) | ゲスト制御デーモン `vphoned` |
+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | ゲスト用フックと補助バイナリ |
+| [`Documents/`](README.md) | 設定、使用方法、互換性、トラブルシューティング |
+| [`Research/`](../Research/README.md) | パッチと実装に関する研究記録 |
-ビルド中に生成された `VPhone.bundle` が自動で検証されます。
+## 謝辞
-AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](Guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。
+- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
diff --git a/Documents/README_ko.md b/Documents/README_ko.md
index 68f9bcc7..12d7301a 100644
--- a/Documents/README_ko.md
+++ b/Documents/README_ko.md
@@ -1,49 +1,77 @@
-<div align="right"><a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <strong>한국어</strong></div>
+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <strong>한국어</strong></div>
# vphone-cli
-Apple Virtualization.framework와 PCC 연구용 VM 기반으로 가상 iPhone을 부팅합니다.
+> [!WARNING]
+> 버전 2.0은 개발 중입니다. 안정 버전이 필요하면 [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14)를 사용하세요.
+
+Apple Silicon Mac에서 가상 iPhone을 만들고 실행합니다. vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 VM 기반을 사용합니다.
![macOS에서 실행 중인 가상 iPhone](demo.jpeg)
-공개 펌웨어 흐름은 **JB 한 가지**입니다. 필요한 시스템 패치와 호스트 제어용 vphoned를 설치합니다. 게스트 사용자 환경은 그대로 두며 패키지 관리자, SSH, VNC 또는 첫 부팅 bootstrap은 설치하지 않습니다.
+버전 2.0에서는 1.0의 무겁고 복잡한 호스트 설정을 상당 부분 없애고 커스텀 펌웨어에 필요한 시스템 수정 사항을 간소화했습니다. 핵심 흐름이 어느 정도 안정되어 구성은 **JB 한 가지**로 정리했습니다. 독립적으로 실행 가능한 `VPhone.bundle`의 CLI에서 펌웨어 다운로드부터 설치와 시작까지 처리합니다.
-## 빠른 시작
+현재 권장하는 호스트 설정은 macOS 복구 환경에서 `csrutil enable --without debug`와 `csrutil allow-research-guests enable`을 실행하는 것입니다. SIP는 켜진 상태로 유지되고 디버깅 제한만 완화됩니다. AMFI가 VM 바이너리를 허용하도록 하려면 root 권한이 필요합니다. 절차는 [호스트 설정](Guides/host-setup.md), 원리는 [amfi-allow 연구 자료](https://github.com/Lakr233/amfi-allow)를 참고하세요. 향후 `vphone-ui.app`에서는 설정을 더 쉽게 하고 설치 단계의 수정 사항을 선택할 수 있게 할 예정입니다.
-Apple Silicon Mac, macOS 15 이상, 그리고 PV=3 연구용 VM과 `vphone-vm` 권한을 허용하는 [호스트 설정](Guides/host-setup.md)이 필요합니다.
+## 시작하기
-**v2.0.0 VM 호환성:** 이 릴리스는 새로 만든 `schemaVersion=2` VM만 시작합니다. 이전 버전에서 만든 VM은 `vm create`로 다시 만들어야 하며, 기존 VM의 제자리 업그레이드는 지원하지 않습니다.
+macOS 15 이상이 설치된 Apple Silicon Mac, 소스 빌드용 Xcode, iPhone 복원 IPSW, 호환되는 cloudOS IPSW가 필요합니다. [호스트 설정](Guides/host-setup.md)에 따라 VM의 비공개 권한을 허용하고 [검증된 펌웨어 조합](Guides/compatibility.md)을 확인하세요. 중첩된 macOS VM에서는 게스트를 실행할 수 없습니다.
```sh
+git clone https://github.com/Lakr233/vphone-cli.git
+cd vphone-cli
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+export PATH="$PWD/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS:$PATH"
+
+vphone-cli host preflight
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
--cloudos-source /path/to/cloudOS.ipsw
-
vphone-cli vm launch myphone
```
-`vm create`는 준비, JB 패치, DFU 복원, CFW 설치를 수행하고 첫 부팅에서 vphoned에 실제로 ping합니다. **검증용 부팅은 성공 후 종료됩니다.** 계속 사용하려면 `vm launch`를 실행하세요. 복원에는 네트워크가, CFW 설치에는 관리자 인증이 필요합니다.
+`vm create`는 게스트 준비와 복원, JB 시스템 변경 설치, `vphoned` 응답 확인을 수행합니다. 확인용 부팅은 완료 후 중지되므로, 실제 사용을 위해 `vm launch`로 VM 창을 여세요. 생성에는 네트워크 연결이, CFW 설치에는 관리자 권한이 필요합니다. 자세한 내용은 [생성 및 실행 가이드](Guides/create-and-run.md)를 참고하세요.
-cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435`)이 잠금 화면에 도달하고 vphoned ping에 응답했습니다. 범위는 [호환성 기록](Guides/compatibility.md)을 참고하세요.
+2.x 버전은 `schemaVersion=2` 형식으로 생성한 VM만 시작할 수 있습니다. 이전 버전의 VM은 다시 만들어야 합니다.
-## 설치와 빌드
+## 커스텀 펌웨어 Bootstrap
-Xcode는 나중에 `vphone-workstation`이 통합할 `VPhone.bundle`을 만듭니다. 실행 시 Homebrew, Python, Xcode가 필요하지 않습니다. 번들 안의 CLI를 직접 실행할 수 있습니다.
+VM을 실행한 뒤 macOS 메뉴 막대에서 **Guest > Install Bootstrap…**을 선택하고 환경 레이아웃을 고르세요. 그러면 게스트에 Irisin이 설치됩니다.
-```sh
-.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
-```
+현재는 Irisin에서 `coreutils`, `debianutils`, `dash` 등의 기본 패키지를 하나씩 설치해야 합니다. 패키지 스크립트 오류로 설치가 실패하면 실패한 작업 화면 왼쪽 위의 **More** 메뉴에서 **Ignore Script Errors and Retry**를 선택하세요. 스크립트는 실행되지만 오류를 무시하고 계속 진행합니다. 환경이 준비되면 일반 설치 방식으로 돌아갈 수 있습니다. 이 초기 설정 과정은 후속 버전에서 개선할 예정입니다.
-위 예시의 `vphone-cli` 대신 이 앱 내부 경로를 사용할 수 있습니다. 소스 빌드에는 vphoned용 iPhoneOS SDK가 포함된 Xcode가 필요합니다.
+## 기본 사용법
-```sh
-git clone https://github.com/Lakr233/vphone-cli.git
-cd vphone-cli
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-```
+VM 창에서 앱과 파일 탐색, 클립보드와 설정 관리, 스크린샷, 녹화, 진단 기능을 사용할 수 있습니다. 로컬 자동화에는 `--api-listen 127.0.0.1:8765` 옵션으로 실행하세요. 자세한 내용은 [게스트 API](../Research/vphoned_http_api.md)를 참고하세요.
+
+| 작업 | 명령 |
+| --- | --- |
+| VM 목록 | `vphone-cli vm list` |
+| VM 정보 | `vphone-cli vm info myphone` |
+| VM 창 시작 | `vphone-cli vm launch myphone` |
+| VM 중지 | `vphone-cli vm stop myphone` |
+| 백업 내보내기 | `vphone-cli vm export myphone --out myphone.tzst` |
+| 백업 가져오기 | `vphone-cli vm import myphone.tzst --name restored` |
+
+VM은 기본적으로 `~/.vphone/`에 저장됩니다. 다른 명령은 `vphone-cli <group> --help`에서 확인할 수 있습니다.
+
+## 구성
+
+`vphone-cli`는 펌웨어 준비, VM 복원 및 수명 주기 관리를 담당합니다. 번들에 포함된 `vphone-vm`이 게스트를 실행하고 macOS 창을 관리합니다. 게스트 내부의 `vphoned`는 창의 제어 기능과 선택적으로 공개하는 HTTP·WebSocket API를 제공합니다. Xcode의 `VPhone` scheme은 독립적으로 실행 가능한 `VPhone.bundle`을 빌드하고 검증합니다.
+
+## 저장소 안내
+
+| 경로 | 내용 |
+| --- | --- |
+| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI, VM 프로세스, 펌웨어 패치 도구, 복원 백엔드 |
+| [`VPhoneKit/`](../VPhoneKit/) | 호스트 공용 라이브러리와 API 클라이언트 |
+| [`VPhoneDaemon/`](../VPhoneDaemon/) | 게스트 제어 데몬 `vphoned` |
+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 게스트 후크와 지원 바이너리 |
+| [`Documents/`](README.md) | 설정, 사용법, 호환성, 문제 해결 가이드 |
+| [`Research/`](../Research/README.md) | 패치 및 구현 연구 기록 |
-빌드 과정에서 생성된 `VPhone.bundle`을 자동으로 검증합니다.
+## 감사의 말
-AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](Guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.
+- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
diff --git a/Documents/README_zh.md b/Documents/README_zh.md
index 209613a7..a105c65f 100644
--- a/Documents/README_zh.md
+++ b/Documents/README_zh.md
@@ -1,62 +1,77 @@
-<div align="right"><strong>中文</strong> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a></div>
+<div align="right"><a href="../README.md">English</a> · <strong>中文</strong> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a></div>
# vphone-cli
-用 Apple Virtualization.framework 和 PCC 研究虚拟机基础设施启动虚拟 iPhone。
+> [!WARNING]
+> 2.0 版仍在开发中。需要稳定版本请使用 [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14)。
-![运行中的虚拟 iPhone](demo.jpeg)
+在 Apple Silicon Mac 上创建和运行虚拟 iPhone。vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机基础设施。
-目前公开的固件流程**只有 JB 一种**:打齐必要的系统补丁并安装 vphoned,方便宿主机控制。访客用户环境保持空白;本项目不会安装 Sileo、apt、TrollStore、SSH、VNC 或首次启动 bootstrap。
+![在 macOS 上运行的虚拟 iPhone](demo.jpeg)
-## 快速开始
+2.0 移除了 1.0 中不少繁重的宿主机环境配置,也精简了定制固件所需的系统修复。目前核心流程已趋于稳定,因此只保留一套 **JB** 配置:自包含的 `VPhone.bundle` 通过其中的 CLI 完成固件下载、安装和启动。
-需要 Apple Silicon Mac、macOS 15 或更新版本,以及允许 PV=3 研究虚拟机和 `vphone-vm` 私有授权的宿主机设置。先看[宿主机准备](Guides/host-setup.md)。
+目前推荐在 macOS 恢复模式中执行 `csrutil enable --without debug` 和 `csrutil allow-research-guests enable`。这样会保留 SIP,但放宽调试限制。让 AMFI 放行虚拟机程序需要 root 权限;具体步骤见[宿主机设置](Guides/host-setup.md),原理见 [amfi-allow 研究项目](https://github.com/Lakr233/amfi-allow)。后续的 `vphone-ui.app` 会简化设置,并提供安装阶段修复项的开关。
-**v2.0.0 虚拟机兼容性:**此版本只能启动新建的、`schemaVersion=2` 的虚拟机。旧版本创建的虚拟机必须重新执行 `vm create` 创建;不支持原地升级。
+## 开始使用
+
+需要运行 macOS 15 或更新版本的 Apple Silicon Mac、用于源码构建的 Xcode、iPhone 恢复 IPSW,以及兼容的 cloudOS IPSW。先按[宿主机设置](Guides/host-setup.md)允许虚拟机所需的私有授权,并查看[已验证的固件组合](Guides/compatibility.md)。不能在嵌套的 macOS 虚拟机中运行访客系统。
```sh
+git clone https://github.com/Lakr233/vphone-cli.git
+cd vphone-cli
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+export PATH="$PWD/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS:$PATH"
+
+vphone-cli host preflight
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
--cloudos-source /path/to/cloudOS.ipsw
-
vphone-cli vm launch myphone
```
-`vm create` 会完成固件准备、JB 补丁、DFU 恢复、CFW 安装,并在首次启动时真正 ping 一次 vphoned。**验收成功后,它会关闭这次临时启动**;要继续使用,请再执行 `vm launch`。恢复阶段需要网络,CFW 安装需要管理员认证。两个 VM 请依次创建,避免磁盘与内存占用叠加。
+`vm create` 准备和恢复访客系统、安装 JB 系统改动,并确认 `vphoned` 能响应。验证完成后,它会停止本次启动;执行 `vm launch` 才会打开供日常使用的虚拟机窗口。创建过程需要网络,安装 CFW 需要管理员权限。详见[创建与运行指南](Guides/create-and-run.md)。
-已用 cloudOS 26.4(`23E5207q`)验证 iPhone17,3 的 iOS 26.6.2(`23G90`)和 27.0(`24A435`):两者都到达锁屏并收到 vphoned ping。其他组合请看[兼容性记录](Guides/compatibility.md),不要把它们视为已完成同等验收。
+2.x 版只能启动以 `schemaVersion=2` 格式创建的虚拟机。旧版虚拟机需要重新创建。
-## 安装与构建
+## 定制固件 Bootstrap
-Xcode 现在直接生成供后续 `vphone-workstation` 集成的 `VPhone.bundle`。运行时不需要 Homebrew、Python 或 Xcode;bundle 内没有 app 启动器或自动提权服务。可以直接调用其中的 CLI:
+启动虚拟机后,在 macOS 菜单栏选择 **Guest > Install Bootstrap…**,再选择所需的环境布局。此操作会在访客系统内安装 Irisin。
-```sh
-.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
-```
+目前需要在 Irisin 中依次安装 `coreutils`、`debianutils`、`dash` 等基础软件包。如果安装因软件包脚本出错而失败,请打开失败操作页面左上角的 **More** 菜单,选择 **Ignore Script Errors and Retry**。Irisin 仍会运行脚本,但会忽略脚本错误继续安装。环境就绪后,即可恢复正常安装。后续版本会改善这段初始配置流程。
-上文示例中的 `vphone-cli` 可替换为上述 bundle 内路径。从源码构建需要 Xcode 的 iPhoneOS SDK,以编译 vphoned:
+## 日常使用
-```sh
-git clone https://github.com/Lakr233/vphone-cli.git
-cd vphone-cli
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-```
-
-构建会自动验收生成的 `VPhone.bundle`。
-
-采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](Guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。
-
-## 常用命令
+虚拟机窗口提供 App 和文件浏览、剪贴板与偏好设置工具、截图、录屏及诊断功能。需要本机自动化接口时,可用 `--api-listen 127.0.0.1:8765` 启动;详见[访客 API](../Research/vphoned_http_api.md)。
| 操作 | 命令 |
| --- | --- |
| 列出虚拟机 | `vphone-cli vm list` |
-| 启动窗口 | `vphone-cli vm launch myphone` |
+| 查看虚拟机 | `vphone-cli vm info myphone` |
+| 启动虚拟机窗口 | `vphone-cli vm launch myphone` |
| 停止虚拟机 | `vphone-cli vm stop myphone` |
| 导出备份 | `vphone-cli vm export myphone --out myphone.tzst` |
| 导入备份 | `vphone-cli vm import myphone.tzst --name restored` |
-| 查看固件配对 | `vphone-cli fw catalog` |
-虚拟机和固件缓存默认位于 `~/.vphone/`。完整步骤、手动流水线和存储路径见[创建与运行指南](Guides/create-and-run.md)。[文档目录](README.md)汇总其余指南;[研究目录](../Research/README.md)收录补丁与实现记录。详细指南目前以英文为准。
+虚拟机默认保存在 `~/.vphone/`。更多命令可运行 `vphone-cli <group> --help` 查看。
+
+## 架构简述
+
+`vphone-cli` 负责准备固件、恢复虚拟机并管理其生命周期。bundle 中的 `vphone-vm` 运行访客系统并管理 macOS 窗口。访客系统内的 `vphoned` 为窗口以及可选的 HTTP 和 WebSocket API 提供控制能力。Xcode 的 `VPhone` scheme 会构建并验证自包含的 `VPhone.bundle`。
+
+## 仓库目录
+
+| 路径 | 内容 |
+| --- | --- |
+| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI、虚拟机进程、固件补丁与恢复后端 |
+| [`VPhoneKit/`](../VPhoneKit/) | 宿主机共享库与 API 客户端 |
+| [`VPhoneDaemon/`](../VPhoneDaemon/) | 访客控制服务 `vphoned` |
+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 访客系统 hook 与辅助程序 |
+| [`Documents/`](README.md) | 设置、使用、兼容性和故障排查指南 |
+| [`Research/`](../Research/README.md) | 补丁与实现研究记录 |
+
+## 致谢
+
+- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
diff --git a/README.md b/README.md
index 91a31fc8..e7910772 100644
--- a/README.md
+++ b/README.md
@@ -1,84 +1,76 @@
-<div align="right"><a href="Documents/README.md">Documentation and translations</a></div>
+<div align="right"><a href="Documents/README.md">Docs</a> · <a href="Documents/README_zh.md">中文</a> · <a href="Documents/README_ja.md">日本語</a> · <a href="Documents/README_ko.md">한국어</a></div>
# vphone-cli
> [!WARNING]
-> **Version 2.0 is under construction.** If you need a stable version, check out the [1.0.14 release](https://github.com/Lakr233/vphone-cli/tree/1.0.14): `git checkout 1.0.14`.
+> Version 2.0 is under construction. For the stable version, use [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14).
-Boot a virtual iPhone with Apple's Virtualization.framework and PCC research VM infrastructure.
+Create and run a virtual iPhone on an Apple Silicon Mac. vphone-cli uses Apple's Virtualization.framework and PCC research VM infrastructure.
![Virtual iPhone running on macOS](Documents/demo.jpeg)
-The supported firmware flow is **JB only**. It applies the required system patches and installs **vphoned** for host control. It leaves the guest user environment alone: no package manager, SSH server, VNC server, or first-boot bootstrap is installed.
+Version 2.0 removes much of 1.0's heavy host setup and simplifies the system fixes needed by custom firmware. The core flow is now stable enough for a single **JB** configuration: the self-contained `VPhone.bundle` handles firmware download, installation, and launch through its CLI.
-## Quick start
+For now, the recommended host setup runs `csrutil enable --without debug` and `csrutil allow-research-guests enable` in macOS Recovery. SIP remains enabled with debugging restrictions relaxed. Allowing the VM binary through AMFI requires root; see [host setup](Documents/Guides/host-setup.md) and the [amfi-allow research](https://github.com/Lakr233/amfi-allow). A future `vphone-ui.app` will make setup easier and offer switches for installation-time fixes.
-Use an Apple Silicon Mac running macOS 15 or newer. The host must permit PV=3 research guests and the private entitlements on `vphone-vm`; see [host setup](Documents/Guides/host-setup.md) before the first boot. A Mac running inside another VM cannot boot this guest.
+## Get started
-**v2.0.0 VM compatibility:** This release starts only newly created VMs with
-`schemaVersion=2`. VMs created by earlier releases must be recreated with
-`vm create`; there is no in-place upgrade.
+You need an Apple Silicon Mac running macOS 15 or newer, Xcode to build from source, an iPhone restore IPSW, and a compatible cloudOS IPSW. Follow [host setup](Documents/Guides/host-setup.md) to permit the VM's private entitlements, then check the [verified firmware pairs](Documents/Guides/compatibility.md). A nested macOS VM cannot run the guest.
```sh
+git clone https://github.com/Lakr233/vphone-cli.git
+cd vphone-cli
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+export PATH="$PWD/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS:$PATH"
+
+vphone-cli host preflight
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
--cloudos-source /path/to/cloudOS.ipsw
-
vphone-cli vm launch myphone
```
-To expose the guest HTTP and WebSocket API on the host for local tools or an
-app using `VPhoneExternalAccessKit`, opt in when launching:
+`vm create` prepares and restores the guest, installs the JB system changes, and checks that `vphoned` responds. It stops the verification boot when finished; `vm launch` starts the VM window for use. Creation needs network access and administrator privileges for CFW installation. See [create and run](Documents/Guides/create-and-run.md) for details.
-```sh
-vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
-```
+Version 2.x starts only VMs created with its `schemaVersion=2` format. Older VMs must be recreated.
-The guest runs `icli` commands through the API. See the [API design and usage](Research/vphoned_http_api.md)
-for routes, WebSocket messages, and the Swift Kit client.
+## Custom Firmware Bootstrap
-`vm create` prepares and patches firmware, restores the VM, installs the JB system changes and vphoned, then boots once to check a real vphoned ping. **It stops that verification boot before returning.** Run `vm launch` to keep using the VM. The create flow needs network access for Apple's restore ticket and requires the caller to provide root privileges for CFW installation.
+After launching the VM, choose **Guest > Install Bootstrap…** from the macOS menu bar and select a layout. This installs Irisin in the guest.
-For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both reached the lock screen and answered vphoned ping with cloudOS **26.4 (23E5207q)**. See [compatibility and evidence](Documents/Guides/compatibility.md); other firmware combinations are not implied by these results.
+For now, install `coreutils`, `debianutils`, `dash`, and other essential packages in Irisin one at a time. If a package script causes an installation to fail, open the **More** menu at the top left of the failed operation and choose **Ignore Script Errors and Retry**. Irisin still runs the scripts but continues past their errors. Once the environment is ready, return to normal installation. A later release will improve this initial setup.
-## Build the bundle
+## Everyday use
-Xcode builds a self-contained `VPhone.bundle` for a future `vphone-workstation`
-to download and load. The bundle contains no app launcher, installer, privileged
-service or password prompt. Root access and installation belong to the
-workstation. Building from source needs Xcode and its iPhoneOS SDK for vphoned:
-
-```sh
-git clone https://github.com/Lakr233/vphone-cli.git
-cd vphone-cli
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli --help
-```
-
-The `VPhone` scheme builds the host tools, guest daemon, and guest components;
-every shipped binary is under `Contents/MacOS`. They use ad hoc code signatures,
-with private virtualization entitlements only on `vphone-vm`. The build validates
-the finished bundle; run the test schemes in their respective projects. An AMFI
-allowlist must be updated whenever the VM binary's cdhash changes. See
-[host setup](Documents/Guides/host-setup.md) and the
-[bundle integration contract](Documents/Guides/bundle-integration.md).
-
-## Everyday commands
+The VM window provides app and file browsing, clipboard and preference tools, screenshots, recording, and diagnostics. For local automation, launch with `--api-listen 127.0.0.1:8765`; see the [guest API](Research/vphoned_http_api.md).
| Task | Command |
| --- | --- |
| List VMs | `vphone-cli vm list` |
| Inspect a VM | `vphone-cli vm info myphone` |
-| Start its window | `vphone-cli vm launch myphone` |
-| Stop it | `vphone-cli vm stop myphone` |
-| Back it up | `vphone-cli vm export myphone --out myphone.tzst` |
-| Restore a backup | `vphone-cli vm import myphone.tzst --name restored` |
-| Inspect firmware pairings | `vphone-cli fw catalog` |
-| Check the host | `vphone-cli host preflight` |
-
-VMs and downloaded firmware live under `~/.vphone/` by default. `VPHONE_ROOT` relocates the tree; `VPHONE_LIBRARY_ROOT` overrides just the VM library. Use `vphone-cli <group> --help` for current command options.
+| Start the VM window | `vphone-cli vm launch myphone` |
+| Stop a VM | `vphone-cli vm stop myphone` |
+| Export a backup | `vphone-cli vm export myphone --out myphone.tzst` |
+| Import a backup | `vphone-cli vm import myphone.tzst --name restored` |
+
+VMs live under `~/.vphone/` by default. Run `vphone-cli <group> --help` for more commands.
+
+## How it fits together
+
+`vphone-cli` prepares firmware, restores VMs, and manages their lifecycle. The bundled `vphone-vm` runs the guest and owns its macOS window. Inside the guest, `vphoned` provides the controls used by the window and the optional HTTP and WebSocket API. The `VPhone` Xcode scheme builds and validates the self-contained `VPhone.bundle`.
+
+## Repository map
+
+| Path | Contents |
+| --- | --- |
+| [`VPhoneExecutable/`](VPhoneExecutable/) | CLI, VM process, firmware patcher, and restore backend |
+| [`VPhoneKit/`](VPhoneKit/) | Shared host libraries and API client |
+| [`VPhoneDaemon/`](VPhoneDaemon/) | Guest control daemon, `vphoned` |
+| [`VPhoneGuestComponents/`](VPhoneGuestComponents/) | Guest hooks and support binaries |
+| [`Documents/`](Documents/README.md) | Setup, usage, compatibility, and troubleshooting guides |
+| [`Research/`](Research/README.md) | Patch and implementation notes |
## Acknowledgements