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.mdindex 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) を使用してください。-+Apple Silicon Mac 上で仮想 iPhone を作成・実行します。vphone-cli は Apple の Virtualization.framework と PCC 研究用 VM 基盤を使用します。-公開されているファームウェア構成は **JB のみ**です。必要なシステムパッチとホスト制御用の vphoned を導入します。ゲストのユーザー環境はそのままにし、パッケージマネージャー、SSH、VNC、初回起動時の bootstrap はインストールしません。+-## クイックスタート+バージョン 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 preflightvphone-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.mdindex 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 기반을 사용합니다.-공개 펌웨어 흐름은 **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 preflightvphone-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.mdindex 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)。-+在 Apple Silicon Mac 上创建和运行虚拟 iPhone。vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机基础设施。-目前公开的固件流程**只有 JB 一种**:打齐必要的系统补丁并安装 vphoned,方便宿主机控制。访客用户环境保持空白;本项目不会安装 Sileo、apt、TrollStore、SSH、VNC 或首次启动 bootstrap。+-## 快速开始+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 preflightvphone-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.mdindex 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.-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 preflightvphone-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