Run a virtual iPhone on an Apple Silicon Mac.
Swift
Rewrite README in all four languages
Lakrab6e5cbee57e
diff --git a/Documents/README_ja.md b/Documents/README_ja.mdindex 252eba26..ad971228 100644--- a/Documents/README_ja.md+++ b/Documents/README_ja.md@@ -2,65 +2,119 @@# vphone-cli-> 旧バージョンの vphone-cli 1.x をお探しの場合は、[1.0.14 のリリース](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)をご覧ください。--Apple Silicon Mac 上で仮想 iPhone を作成・実行します。vphone-cli は Apple の Virtualization.framework と PCC 研究用 VM 基盤を使用します。+Apple Silicon Mac で仮想 iPhone を実行します。-バージョン 2.x では、以前 EXP として提供していた変更を含む、ファームウェアの完全なパッチセットを適用します。パッチ構成は選択できません。自己完結した `VPhone.bundle` がファームウェアの準備、復元、VM の制御を担い、`vphone-launchpad` が bundle のインストールと VM の作成・起動を案内します。+vphone-cli は Apple の Virtualization.framework と PCC 研究用仮想マシンを使って iOS を実行します。セキュリティ研究、リバースエンジニアリング、デバッグに適しています。++- **グラフィカルウィンドウ**:Mac 上で仮想 iPhone の画面を操作し、App とファイルを閲覧し、スクリーンショットの撮影や画面収録ができます。+- **カスタムファームウェア(Custom Firmware)**:システムにはあらかじめパッチが適用されており、パッケージ環境をインストールできます。+- **バックアップと複製**:仮想マシンの書き出し、読み込み、複製ができます。+- **自動化 API**:任意で有効にできる、ローカルの HTTP と WebSocket のインターフェースです。+- **追加の依存なし**:実行時に Xcode、Python、Homebrew は不要です。++> 1.x については [1.0.14 Release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14) をご覧ください。2.x では 1.x で作成した仮想マシンを起動できないため、作り直す必要があります。++## 準備++- macOS 15 以降を搭載した物理 Apple Silicon Mac。macOS の仮想マシン上では使用できません。+- 十分なディスク容量。仮想マシンごとに標準で 64 GB の仮想ディスクを使用し、ファームウェアと一時ファイルにも別途容量が必要です。+- ネットワーク接続。システムの復元時に署名チケットをオンラインで取得します。+- セキュリティ設定の変更。macOS 復旧モードに入り、ターミナルで次のコマンドを実行してから再起動します。-推奨するホスト設定では、macOS 復旧環境で `csrutil enable --without debug` と `csrutil allow-research-guests enable` を実行します。SIP を有効に保ちつつ、デバッグの制限を緩和します。Launchpad はホストを確認し、特権ヘルパーを使用して検証済みの VM バイナリを AMFI に許可します。詳しくは[ホストの設定](Guides/host-setup.md)をご覧ください。+ ```sh+ csrutil enable --without debug+ csrutil allow-research-guests enable+ ```-## はじめに+ SIP は有効のまま、デバッグの制限だけを緩和します。理由と別の設定方法は[ホストの設定](Guides/host-setup.md)をご覧ください。-macOS 15 以降を搭載した物理 Apple Silicon Mac では、公証済みの [vphone-launchpad 2.1.2](https://github.com/Lakr233/vphone-cli/releases/download/2.1.2/vphone-launchpad-2.1.2-notarized.zip) を使用してください。リリース版の実行に Xcode、Python、Homebrew は不要です。+## クイックスタート-1. macOS 復旧環境で `csrutil enable --without debug` と `csrutil allow-research-guests enable` を実行し、再起動します。詳しくは[ホストの設定](Guides/host-setup.md)をご覧ください。-2. アーカイブを展開してアプリを開きます。**Host Setup** の案内に従い、開発者ツールへのアクセスを許可して特権ヘルパーをインストールします。-3. **Core Bundle** で **Download and Install** を選び、最新の `VPhone.bundle` をインストールします。Launchpad はダウンロードを検証し、VM バイナリをホストで使用できるようにします。-4. **Machines** で **New Machine** を選び、カタログからファームウェアの組み合わせを選択して **Create** をクリックします。Launchpad が初回起動を確認した後も、VM は実行されたままです。+1. 最新の [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<バージョン>.zip`)をダウンロードし、展開して開きます。+2. **Host Setup** で開発者ツールへのアクセスを許可し、ヘルパーをインストールします。+3. **Core Bundle** で **Download and Install** をクリックします。Launchpad が `VPhone.bundle` をダウンロードして検証し、その中の仮想マシン用プログラムがこの Mac で実行できるようにします。+4. **Machines** で **New Machine** をクリックし、ファームウェアの組み合わせを選んで **Create** をクリックします。-カタログの組み合わせを選ぶと、ファームウェアがダウンロードされます。ローカルの IPSW を使う場合も、VM の作成には復元チケット取得のためのネットワーク接続と十分な空き容量が必要です。互換性のある iPhone と cloudOS の IPSW を自分で指定することもできます。検証済みの組み合わせは[互換性ガイド](Guides/compatibility.md)をご覧ください。ソースからのビルドとターミナルでの操作は[ホストの設定](Guides/host-setup.md)と[作成と起動のガイド](Guides/create-and-run.md)を参照してください。+Launchpad がファームウェアのダウンロード、パッチの適用、システムの復元、初回起動を行います。完了後も仮想マシンは実行されたままです。-2.x 版で起動できるのは `schemaVersion=2` 形式で作成された VM だけです。旧版の VM は作り直す必要があります。+自分の iPhone と cloudOS の IPSW を使うこともできます。検証済みの組み合わせは[互換性ガイド](Guides/compatibility.md)をご覧ください。-## カスタムファームウェアの Bootstrap+## パッケージ環境のインストール-VM を起動したら、macOS のメニューバーで **Guest > Install Bootstrap…** を選び、環境のレイアウトを選択します。これによりゲスト内に Irisin がインストールされます。-Option キーを押しながらこのメニューを開くと、ローカルの Irisin `.deb` を選択できます。**Uninstall Bootstrap…** の Option メニューは rootless と RootHide の両環境を削除し、ゲストを再起動しません。通常の削除では再起動します。+仮想マシンには標準でパッケージマネージャが入っていません。インストール手順は次のとおりです。-初回の環境準備では、Irisin で `apt` と `bash` を選択します。**Install** ボタンを長押しし、**Bootstrap Install** を選んでください。このモードでは、今回のインストールに含まれるすべてのパッケージを先に展開してからインストール処理を再実行します。これにより、`debianutils` には `bash` が必要で、`bash` には設定済みの `debianutils` が必要という初期段階の依存関係を回避できます。初回の準備後は通常のインストールを使用できます。+1. メニューバーで **Apps > Install Bootstrap…** を選び、レイアウトとして **roothide** を選択します(**rootless** は非推奨です)。仮想マシンに Irisin がインストールされます。+2. 初回のインストールでは、Irisin で `apt` と `bash` にチェックを入れ、インストールボタンを長押しして **Bootstrap Install** を選びます。`bash` と `debianutils` は相互に依存しているため、通常のインストールでは完了できません。+3. 以降は通常のインストールで構いません。-## 日常の操作+環境を削除するには **Apps > Uninstall Bootstrap…** を選びます。削除後、仮想マシンは再起動します。-VM ウィンドウにはアプリとファイルの閲覧、クリップボードと設定の操作、スクリーンショット、録画、診断機能があります。ローカルの自動化には `--api-listen 127.0.0.1:8765` を指定して起動します。詳しくは[ゲスト API](../Research/vphoned_http_api.md)を参照してください。+Option キーを押しながら **Apps** メニューを開くと、さらに 2 つの項目があります。++- **Install Bootstrap from File…**:ローカルの Irisin `.deb` を使ってインストールします。+- **Uninstall Bootstrap Without Restarting…**:仮想マシンを再起動せずに環境を削除します。++## コマンドライン++Launchpad は `VPhone.bundle` 内の `vphone-cli` を使って仮想マシンを管理しています。ターミナルから直接使うこともできます。| 操作 | コマンド || --- | --- |-| 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` |+| 仮想マシンの一覧表示 | `vphone-cli vm list` |+| 仮想マシンの情報表示 | `vphone-cli vm info myphone` |+| 仮想マシンの起動 | `vphone-cli vm launch myphone` |+| 仮想マシンの停止 | `vphone-cli vm stop myphone` |+| 仮想マシンの複製 | `vphone-cli vm clone myphone copy` |+| 仮想マシンの書き出し | `vphone-cli vm export myphone --out myphone.tzst` |+| 仮想マシンの読み込み | `vphone-cli vm import myphone.tzst --name restored` |++仮想マシンは標準で `~/.vphone/` に保存されます。すべてのコマンドは `vphone-cli <group> --help` で確認できます。Launchpad を使わずに仮想マシンを作成する方法は[作成と実行](Guides/create-and-run.md)をご覧ください。-VM は標準で `~/.vphone/` に保存されます。その他のコマンドは `vphone-cli <group> --help` で確認できます。+### 自動化 API-## 構成+起動時に `--api-listen` を指定すると有効になります。-`vphone-cli` はファームウェアの準備、VM の復元と管理を担当します。bundle 内の `vphone-vm` がゲストを実行し、macOS ウィンドウを管理します。ゲスト内の `vphoned` はウィンドウ操作と、任意で公開する HTTP・WebSocket API を提供します。Xcode の `VPhone` scheme は自己完結した `VPhone.bundle` をビルドして検証します。+```sh+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765+# 出力に [api] token: … と表示されます+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health+```-## リポジトリ案内+token は起動のたびに新しく生成されます。token を固定するには、環境変数 `VPHONE_API_TOKEN` を設定してください。token のないリクエストと Web ページからのリクエストは、どちらも拒否されます。インターフェースの説明は [API ドキュメント](../Research/vphoned_http_api.md)をご覧ください。++## 問題が起きたら++まず[トラブルシューティング](Guides/troubleshooting.md)をご覧ください。仮想マシン用プログラムがシステムに拒否される、復元に失敗する、「Press home to continue」で止まる、といった状況を扱っています。それでも解決しない場合は、[issue を送信](https://github.com/Lakr233/vphone-cli/issues)してください。++## ドキュメント++| ドキュメント | 内容 |+| --- | --- |+| [ホストの設定](Guides/host-setup.md) | SIP と AMFI の設定、ソースからのビルド、環境の確認 |+| [作成と実行](Guides/create-and-run.md) | ファームウェアの入手元、作成の流れ、ストレージとバックアップ |+| [互換性ガイド](Guides/compatibility.md) | 検証済みのファームウェアの組み合わせ |+| [トラブルシューティング](Guides/troubleshooting.md) | よくあるエラーと対処方法 |+| [Launchpad コマンドライン](Guides/launchpad-cli.md) | `vphone-launchpad-cli` でローカルビルドをインストールしてテストする |+| [研究記録](../Research/README.md) | パッチと実装の詳細 |++## プロジェクト構成++- `vphone-launchpad`:Mac App です。`VPhone.bundle` のダウンロードとインストール、ホストの設定を行います。別途配布されます。+- `vphone-cli`:ファームウェアの準備、パッチの適用、システムの復元、仮想マシンの管理を行います。+- `vphone-vm`:仮想マシンを実行し、仮想マシンのウィンドウを表示します。+- `vphoned`:仮想マシン内の制御サービスです。ウィンドウの機能と API は、すべてこれを通じて実現されています。| パス | 内容 || --- | --- |-| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI、VM プロセス、ファームウェアパッチ、復元処理 |-| [`VPhoneKit/`](../VPhoneKit/) | ホスト側の共通ライブラリと API クライアント |-| [`VPhoneDaemon/`](../VPhoneDaemon/) | ゲスト制御デーモン `vphoned` |-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | ゲスト用フックと補助バイナリ |-| [`Documents/`](README.md) | 設定、使用方法、互換性、トラブルシューティング |-| [`Research/`](../Research/README.md) | パッチと実装に関する研究記録 |+| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`、`vphone-vm`、ファームウェアパッチと復元 |+| [`VPhoneKit/`](../VPhoneKit/) | ホスト側の共有ライブラリと API クライアント |+| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 仮想マシン内のフックと補助プログラム |+| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad App とそのヘルパー |++ソースからのビルド:`xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`。成果物は `VPhone.bundle` です。## 謝辞diff --git a/Documents/README_ko.md b/Documents/README_ko.mdindex a3e521b6..17821613 100644--- a/Documents/README_ko.md+++ b/Documents/README_ko.md@@ -2,65 +2,119 @@# vphone-cli-> 이전 버전의 vphone-cli 1.x를 찾으신다면 [1.0.14 릴리스](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)를 확인하세요.--Apple Silicon Mac에서 가상 iPhone을 만들고 실행합니다. vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 VM 기반을 사용합니다.+Apple Silicon Mac에서 가상 iPhone을 실행합니다.-버전 2.x는 이전에 EXP로 제공하던 변경 사항을 포함한 전체 펌웨어 패치 세트를 적용합니다. 패치 구성은 선택할 수 없습니다. 독립적으로 실행 가능한 `VPhone.bundle`이 펌웨어 준비, 복원, VM 제어를 담당하고, `vphone-launchpad`가 bundle 설치와 VM 생성 및 실행을 안내합니다.+vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 가상 머신으로 iOS를 실행하며, 보안 연구, 리버스 엔지니어링, 디버깅에 적합합니다.++- **그래픽 창**: Mac에서 가상 iPhone의 화면을 조작하고, 앱과 파일을 탐색하며, 스크린샷을 찍고 화면을 녹화합니다.+- **커스텀 펌웨어(Custom Firmware)**: 시스템에 패치가 미리 적용되어 있어 패키지 환경을 설치할 수 있습니다.+- **백업과 복제**: 가상 머신을 내보내고, 가져오고, 복제할 수 있습니다.+- **자동화 API**: 선택적으로 사용할 수 있는 로컬 HTTP 및 WebSocket 인터페이스입니다.+- **추가 의존성 없음**: 실행에 Xcode, Python, Homebrew가 필요하지 않습니다.++> 1.x 버전은 [1.0.14 릴리스](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)를 참고하세요. 2.x는 1.x에서 만든 가상 머신을 시작할 수 없으므로 다시 만들어야 합니다.++## 준비 사항++- macOS 15 이상을 실행하는 물리 Apple Silicon Mac. macOS 가상 머신에서는 사용할 수 없습니다.+- 충분한 디스크 공간. 가상 머신마다 기본적으로 64 GB 가상 디스크를 사용하며, 펌웨어와 임시 파일이 별도로 공간을 차지합니다.+- 네트워크 연결. 시스템을 복원할 때 서명 티켓을 온라인으로 받아야 합니다.+- 보안 설정 변경. macOS 복구 모드로 진입하여 터미널에서 다음 명령을 실행한 뒤 재시동합니다.-권장 호스트 설정은 macOS 복구 환경에서 `csrutil enable --without debug`와 `csrutil allow-research-guests enable`을 실행하는 것입니다. SIP를 켠 상태로 유지하면서 디버깅 제한을 완화합니다. Launchpad는 호스트를 확인하고 권한 있는 도우미를 사용하여 검증된 VM 바이너리가 AMFI를 통과하도록 허용합니다. 자세한 내용은 [호스트 설정](Guides/host-setup.md)을 참고하세요.+ ```sh+ csrutil enable --without debug+ csrutil allow-research-guests enable+ ```-## 시작하기+ SIP는 켜진 상태로 유지되며 디버깅 제한만 완화됩니다. 이유와 다른 설정 방법은 [호스트 설정](Guides/host-setup.md)을 참고하세요.-macOS 15 이상을 실행하는 물리 Apple Silicon Mac에서는 공증된 [vphone-launchpad 2.1.2](https://github.com/Lakr233/vphone-cli/releases/download/2.1.2/vphone-launchpad-2.1.2-notarized.zip)를 사용하세요. 릴리스 버전을 실행할 때 Xcode, Python, Homebrew는 필요하지 않습니다.+## 빠른 시작-1. macOS 복구 환경에서 `csrutil enable --without debug`와 `csrutil allow-research-guests enable`을 실행한 다음 재시동하세요. 자세한 내용은 [호스트 설정](Guides/host-setup.md)을 참고하세요.-2. 압축을 풀고 앱을 여세요. **Host Setup**의 안내에 따라 개발자 도구 접근을 허용하고 권한 있는 도우미를 설치하세요.-3. **Core Bundle**에서 **Download and Install**을 선택하여 최신 `VPhone.bundle`을 설치하세요. Launchpad가 다운로드를 검증하고 VM 바이너리를 호스트에서 사용할 수 있도록 준비합니다.-4. **Machines**에서 **New Machine**을 선택하고 카탈로그에서 펌웨어 조합을 고른 다음 **Create**를 클릭하세요. Launchpad가 첫 부팅을 확인한 뒤에도 VM은 계속 실행됩니다.+1. 최신 [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<버전>.zip`)를 내려받아 압축을 풀고 엽니다.+2. **Host Setup**에서 개발자 도구 권한을 부여하고 도우미 프로그램을 설치합니다.+3. **Core Bundle**에서 **Download and Install**을 클릭합니다. Launchpad가 `VPhone.bundle`을 내려받아 검증한 뒤, 그 안의 가상 머신 프로그램이 이 Mac에서 실행되도록 허용합니다.+4. **Machines**에서 **New Machine**을 클릭하고 펌웨어 조합을 선택한 뒤 **Create**를 클릭합니다.-카탈로그의 펌웨어 조합을 선택하면 펌웨어가 다운로드됩니다. 로컬 IPSW를 사용하더라도 VM을 생성하려면 복원 티켓을 받을 네트워크 연결과 충분한 디스크 여유 공간이 필요합니다. 호환되는 iPhone 및 cloudOS IPSW를 직접 지정할 수도 있습니다. 검증된 조합은 [호환성 가이드](Guides/compatibility.md)를 참고하세요. 소스 빌드와 터미널 사용법은 [호스트 설정](Guides/host-setup.md) 및 [생성 및 실행 가이드](Guides/create-and-run.md)를 확인하세요.+Launchpad가 펌웨어를 내려받고, 패치를 적용하고, 시스템을 복원한 뒤 첫 부팅을 진행합니다. 완료되면 가상 머신은 계속 실행됩니다.-2.x 버전은 `schemaVersion=2` 형식으로 생성한 VM만 시작할 수 있습니다. 이전 버전의 VM은 다시 만들어야 합니다.+직접 준비한 iPhone 및 cloudOS IPSW를 사용할 수도 있습니다. 검증된 조합은 [호환성 안내](Guides/compatibility.md)를 참고하세요.-## 커스텀 펌웨어 Bootstrap+## 패키지 환경 설치-VM을 실행한 뒤 macOS 메뉴 막대에서 **Guest > Install Bootstrap…**을 선택하고 환경 레이아웃을 고르세요. 그러면 게스트에 Irisin이 설치됩니다.-Option 키를 누른 채 이 메뉴를 열면 로컬 Irisin `.deb` 파일을 선택할 수 있습니다. **Uninstall Bootstrap…**의 Option 메뉴는 rootless와 RootHide 환경을 모두 삭제하지만 게스트를 재시동하지 않습니다. 일반 제거는 삭제 후 재시동합니다.+가상 머신에는 기본적으로 패키지 관리자가 없습니다. 설치 방법은 다음과 같습니다.-환경을 처음 준비할 때는 Irisin에서 `apt`와 `bash`를 선택하세요. **Install** 버튼을 길게 누른 다음 **Bootstrap Install**을 선택하세요. 이 모드는 이번 설치에 포함된 모든 패키지를 먼저 압축 해제한 뒤 설치 절차를 다시 실행합니다. 따라서 `debianutils`에는 `bash`가 필요하지만 `bash`에는 이미 설정된 `debianutils`가 필요한 초기 의존성 순환을 우회할 수 있습니다. 첫 준비가 끝나면 일반 설치 방식을 사용하면 됩니다.+1. 메뉴 막대에서 **Apps > Install Bootstrap…**을 선택하고 레이아웃으로 **roothide**를 선택합니다(**rootless**는 더 이상 권장되지 않습니다). 가상 머신에 Irisin이 설치됩니다.+2. 처음 설치할 때는 Irisin에서 `apt`와 `bash`를 선택하고 설치 버튼을 길게 누른 뒤 **Bootstrap Install**을 선택합니다. `bash`와 `debianutils`는 서로 의존하므로 일반 설치로는 완료할 수 없습니다.+3. 이후에는 일반 설치를 사용하면 됩니다.-## 기본 사용법+환경을 삭제하려면 **Apps > Uninstall Bootstrap…**을 선택합니다. 삭제 후 가상 머신이 재시동됩니다.-VM 창에서 앱과 파일 탐색, 클립보드와 설정 관리, 스크린샷, 녹화, 진단 기능을 사용할 수 있습니다. 로컬 자동화에는 `--api-listen 127.0.0.1:8765` 옵션으로 실행하세요. 자세한 내용은 [게스트 API](../Research/vphoned_http_api.md)를 참고하세요.+Option 키를 누른 채 **Apps** 메뉴를 열면 두 가지 항목이 더 있습니다.++- **Install Bootstrap from File…**: 로컬 Irisin `.deb`로 설치합니다.+- **Uninstall Bootstrap Without Restarting…**: 가상 머신을 재시동하지 않고 환경을 삭제합니다.++## 명령줄++Launchpad는 `VPhone.bundle` 안의 `vphone-cli`로 가상 머신을 관리하며, 터미널에서 직접 사용할 수도 있습니다.| 작업 | 명령 || --- | --- |-| 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` |+| 가상 머신 목록 보기 | `vphone-cli vm list` |+| 가상 머신 정보 보기 | `vphone-cli vm info myphone` |+| 가상 머신 시작 | `vphone-cli vm launch myphone` |+| 가상 머신 중지 | `vphone-cli vm stop myphone` |+| 가상 머신 복제 | `vphone-cli vm clone myphone copy` |+| 가상 머신 내보내기 | `vphone-cli vm export myphone --out myphone.tzst` |+| 가상 머신 가져오기 | `vphone-cli vm import myphone.tzst --name restored` |++가상 머신은 기본적으로 `~/.vphone/`에 저장됩니다. 전체 명령은 `vphone-cli <group> --help`로 확인하세요. Launchpad 없이 가상 머신을 만드는 방법은 [생성 및 실행](Guides/create-and-run.md)을 참고하세요.-VM은 기본적으로 `~/.vphone/`에 저장됩니다. 다른 명령은 `vphone-cli <group> --help`에서 확인할 수 있습니다.+### 자동화 API-## 구성+시작할 때 `--api-listen`을 추가하면 활성화됩니다.-`vphone-cli`는 펌웨어 준비, VM 복원 및 수명 주기 관리를 담당합니다. 번들에 포함된 `vphone-vm`이 게스트를 실행하고 macOS 창을 관리합니다. 게스트 내부의 `vphoned`는 창의 제어 기능과 선택적으로 공개하는 HTTP·WebSocket API를 제공합니다. Xcode의 `VPhone` scheme은 독립적으로 실행 가능한 `VPhone.bundle`을 빌드하고 검증합니다.+```sh+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765+# 출력에 [api] token: …이 표시됩니다+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health+```-## 저장소 안내+시작할 때마다 새 token이 생성됩니다. 고정된 token을 사용하려면 환경 변수 `VPHONE_API_TOKEN`을 설정하세요. token이 없는 요청과 웹 페이지에서 온 요청은 모두 거부됩니다. 인터페이스 설명은 [API 문서](../Research/vphoned_http_api.md)를 참고하세요.++## 문제가 생기면++먼저 [문제 해결](Guides/troubleshooting.md)을 확인하세요. 시스템이 가상 머신 프로그램을 거부하는 경우, 복원 실패, “Press home to continue”에서 멈추는 경우 등을 다룹니다. 그래도 해결되지 않으면 [이슈를 등록](https://github.com/Lakr233/vphone-cli/issues)해 주세요.++## 문서++| 문서 | 내용 |+| --- | --- |+| [호스트 설정](Guides/host-setup.md) | SIP 및 AMFI 설정, 소스 빌드, 환경 점검 |+| [생성 및 실행](Guides/create-and-run.md) | 펌웨어 출처, 생성 절차, 저장과 백업 |+| [호환성 안내](Guides/compatibility.md) | 검증된 펌웨어 조합 |+| [문제 해결](Guides/troubleshooting.md) | 자주 발생하는 오류와 해결 방법 |+| [Launchpad 명령줄](Guides/launchpad-cli.md) | `vphone-launchpad-cli`로 로컬 빌드 설치 및 테스트 |+| [연구 기록](../Research/README.md) | 패치와 구현 세부 사항 |++## 프로젝트 구조++- `vphone-launchpad`: `VPhone.bundle`을 내려받아 설치하고 호스트를 설정하는 Mac 앱입니다. 별도로 배포됩니다.+- `vphone-cli`: 펌웨어 준비, 패치 적용, 시스템 복원, 가상 머신 관리를 담당합니다.+- `vphone-vm`: 가상 머신을 실행하고 가상 머신 창을 표시합니다.+- `vphoned`: 가상 머신 안의 제어 서비스로, 창의 기능과 API는 모두 이를 통해 동작합니다.| 경로 | 내용 || --- | --- |-| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI, VM 프로세스, 펌웨어 패치 도구, 복원 백엔드 |+| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, 펌웨어 패치와 복원 || [`VPhoneKit/`](../VPhoneKit/) | 호스트 공용 라이브러리와 API 클라이언트 |-| [`VPhoneDaemon/`](../VPhoneDaemon/) | 게스트 제어 데몬 `vphoned` |-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 게스트 후크와 지원 바이너리 |-| [`Documents/`](README.md) | 설정, 사용법, 호환성, 문제 해결 가이드 |-| [`Research/`](../Research/README.md) | 패치 및 구현 연구 기록 |+| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 가상 머신 안의 hook과 도우미 프로그램 |+| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad 앱과 도우미 프로그램 |++소스에서 빌드하려면 `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`를 실행합니다. 결과물은 `VPhone.bundle`입니다.## 감사의 말diff --git a/Documents/README_zh.md b/Documents/README_zh.mdindex d1a1dc66..0519d48f 100644--- a/Documents/README_zh.md+++ b/Documents/README_zh.md@@ -2,65 +2,119 @@# vphone-cli-> 查找旧版 1.x?请前往 [1.0.14 Release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)。--在 Apple Silicon Mac 上创建和运行虚拟 iPhone。vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机基础设施。+在 Apple Silicon Mac 上运行虚拟 iPhone。-2.x 会应用完整的固件补丁集,包含此前作为 EXP 提供的改动;目前不能选择不同的补丁方案。自包含的 `VPhone.bundle` 负责固件准备、恢复和虚拟机控制;`vphone-launchpad` 负责安装 bundle,并引导你创建和运行虚拟机。+vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机运行 iOS,适合安全研究、逆向和调试。++- **图形窗口**:在 Mac 上操作虚拟 iPhone 的屏幕,浏览 App 和文件,截图、录屏。+- **自定义固件(Custom Firmware)**:系统已预先打好补丁,可以安装软件包环境。+- **备份与克隆**:虚拟机可以导出、导入和克隆。+- **自动化 API**:可选的本机 HTTP 和 WebSocket 接口。+- **无需额外依赖**:运行时不需要 Xcode、Python 或 Homebrew。++> 1.x 版本请前往 [1.0.14 Release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)。2.x 无法启动 1.x 创建的虚拟机,需要重新创建。++## 准备工作++- 一台实体 Apple Silicon Mac,运行 macOS 15 或更新版本。macOS 虚拟机中无法使用。+- 足够的磁盘空间。每台虚拟机默认使用 64 GB 虚拟磁盘,固件和临时文件另外占用空间。+- 网络连接。恢复系统时需要在线获取签名票据。+- 修改安全设置。进入 macOS 恢复模式,在终端中执行以下命令,然后重新启动:-推荐在 macOS 恢复模式中执行 `csrutil enable --without debug` 和 `csrutil allow-research-guests enable`。这样会保留 SIP,但放宽调试限制。Launchpad 会检查宿主机,并通过特权辅助程序让 AMFI 放行已验证的虚拟机程序;详见[宿主机设置](Guides/host-setup.md)。+ ```sh+ csrutil enable --without debug+ csrutil allow-research-guests enable+ ```-## 开始使用+ SIP 仍保持开启,只放宽调试限制。原因和其他设置方式见[宿主机设置](Guides/host-setup.md)。-推荐在运行 macOS 15 或更新版本的实体 Apple Silicon Mac 上使用已公证的 [vphone-launchpad 2.1.2](https://github.com/Lakr233/vphone-cli/releases/download/2.1.2/vphone-launchpad-2.1.2-notarized.zip)。运行发布版无需 Xcode、Python 或 Homebrew。+## 快速开始-1. 在 macOS 恢复模式中执行 `csrutil enable --without debug` 和 `csrutil allow-research-guests enable`,然后重新启动。详见[宿主机设置](Guides/host-setup.md)。-2. 解压并打开 App,按 **Host Setup** 的提示授予开发者工具权限并安装特权辅助程序。-3. 在 **Core Bundle** 中点击 **Download and Install**,安装最新的 `VPhone.bundle`。Launchpad 会验证下载内容,并完成虚拟机程序的宿主机准备。-4. 在 **Machines** 中点击 **New Machine**,从目录选择固件组合,再点击 **Create**。Launchpad 完成首次启动检查后,虚拟机会保持运行。+1. 下载最新的 [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<版本>.zip`),解压并打开。+2. 在 **Host Setup** 中授予开发者工具权限,并安装辅助程序。+3. 在 **Core Bundle** 中点击 **Download and Install**。Launchpad 会下载并校验 `VPhone.bundle`,然后允许其中的虚拟机程序在本机运行。+4. 在 **Machines** 中点击 **New Machine**,选择一组固件,点击 **Create**。-选择目录中的固件组合时会下载固件。即使使用本地 IPSW,创建虚拟机仍需联网获取恢复票据,并留出充足的磁盘空间。也可以自行提供兼容的 iPhone 和 cloudOS IPSW;已验证的组合见[兼容性说明](Guides/compatibility.md)。源码构建和命令行操作见[宿主机设置](Guides/host-setup.md)与[创建与运行指南](Guides/create-and-run.md)。+Launchpad 会下载固件、打补丁、恢复系统并首次启动。完成后虚拟机会继续运行。-2.x 版只能启动以 `schemaVersion=2` 格式创建的虚拟机。旧版虚拟机需要重新创建。+也可以使用自己的 iPhone 和 cloudOS IPSW,已验证的组合见[兼容性说明](Guides/compatibility.md)。-## 定制固件 Bootstrap+## 安装软件包环境-启动虚拟机后,在 macOS 菜单栏选择 **Guest > Install Bootstrap…**,再选择所需的环境布局。此操作会在访客系统内安装 Irisin。-按住 Option 打开此菜单项可选取本地 Irisin `.deb`;按住 Option 打开 **Uninstall Bootstrap…** 会同时删除现存的 rootless 和 RootHide 环境,但不重启客体。普通卸载会在删除后重启。+虚拟机默认不带软件包管理器。安装步骤:-首次准备环境时,在 Irisin 中选中 `apt` 和 `bash`,长按**安装**按钮,然后选择**引导安装(Bootstrap Install)**。这种模式会先解压本次安装涉及的所有软件包,再重新执行安装流程,以绕过初始阶段的依赖循环:`debianutils` 需要 `bash`,而 `bash` 又需要已经配置好的 `debianutils`。首次准备完成后,即可使用普通安装模式。+1. 在菜单栏选择 **Apps > Install Bootstrap…**,布局选择 **roothide**(**rootless** 已弃用)。虚拟机中会安装 Irisin。+2. 首次安装时,在 Irisin 中勾选 `apt` 和 `bash`,长按安装按钮,选择 **Bootstrap Install**。`bash` 和 `debianutils` 互相依赖,普通安装无法完成。+3. 之后使用普通安装即可。-## 日常使用+要删除环境,选择 **Apps > Uninstall Bootstrap…**,删除后虚拟机会重启。-虚拟机窗口提供 App 和文件浏览、剪贴板与偏好设置工具、截图、录屏及诊断功能。需要本机自动化接口时,可用 `--api-listen 127.0.0.1:8765` 启动;详见[访客 API](../Research/vphoned_http_api.md)。+按住 Option 打开 **Apps** 菜单,还有两个选项:++- **Install Bootstrap from File…**:使用本地的 Irisin `.deb` 安装。+- **Uninstall Bootstrap Without Restarting…**:删除环境,不重启虚拟机。++## 命令行++Launchpad 通过 `VPhone.bundle` 中的 `vphone-cli` 管理虚拟机,你也可以在终端中直接使用:| 操作 | 命令 || --- | --- || 列出虚拟机 | `vphone-cli vm list` |-| 查看虚拟机 | `vphone-cli vm info myphone` |-| 启动虚拟机窗口 | `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 vm clone myphone copy` |+| 导出虚拟机 | `vphone-cli vm export myphone --out myphone.tzst` |+| 导入虚拟机 | `vphone-cli vm import myphone.tzst --name restored` |++虚拟机默认保存在 `~/.vphone/`。运行 `vphone-cli <group> --help` 查看全部命令。不使用 Launchpad 创建虚拟机的方法见[创建与运行](Guides/create-and-run.md)。-虚拟机默认保存在 `~/.vphone/`。更多命令可运行 `vphone-cli <group> --help` 查看。+### 自动化 API-## 架构简述+启动时加上 `--api-listen` 即可开启:-`vphone-cli` 负责准备固件、恢复虚拟机并管理其生命周期。bundle 中的 `vphone-vm` 运行访客系统并管理 macOS 窗口。访客系统内的 `vphoned` 为窗口以及可选的 HTTP 和 WebSocket API 提供控制能力。Xcode 的 `VPhone` scheme 会构建并验证自包含的 `VPhone.bundle`。+```sh+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765+# 输出中会显示 [api] token: …+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health+```-## 仓库目录+每次启动都会生成新的 token。要使用固定的 token,请设置环境变量 `VPHONE_API_TOKEN`。不带 token 的请求和来自网页的请求都会被拒绝。接口说明见 [API 文档](../Research/vphoned_http_api.md)。++## 遇到问题++请先查看[故障排查](Guides/troubleshooting.md),其中包括虚拟机程序被系统拒绝、恢复失败、停在 “Press home to continue” 等情况。如果仍未解决,请[提交 issue](https://github.com/Lakr233/vphone-cli/issues)。++## 文档++| 文档 | 内容 |+| --- | --- |+| [宿主机设置](Guides/host-setup.md) | SIP 与 AMFI 设置、源码构建、环境检查 |+| [创建与运行](Guides/create-and-run.md) | 固件来源、创建流程、存储与备份 |+| [兼容性说明](Guides/compatibility.md) | 已验证的固件组合 |+| [故障排查](Guides/troubleshooting.md) | 常见错误及解决方法 |+| [Launchpad 命令行](Guides/launchpad-cli.md) | 用 `vphone-launchpad-cli` 安装和测试本地构建 |+| [研究记录](../Research/README.md) | 补丁与实现细节 |++## 项目结构++- `vphone-launchpad`:Mac App,负责下载和安装 `VPhone.bundle`、配置宿主机。单独发布。+- `vphone-cli`:准备固件、打补丁、恢复系统、管理虚拟机。+- `vphone-vm`:运行虚拟机并显示虚拟机窗口。+- `vphoned`:虚拟机中的控制服务,窗口中的功能和 API 都通过它实现。| 路径 | 内容 || --- | --- |-| [`VPhoneExecutable/`](../VPhoneExecutable/) | CLI、虚拟机进程、固件补丁与恢复后端 |+| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`、`vphone-vm`、固件补丁与恢复 || [`VPhoneKit/`](../VPhoneKit/) | 宿主机共享库与 API 客户端 |-| [`VPhoneDaemon/`](../VPhoneDaemon/) | 访客控制服务 `vphoned` |-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 访客系统 hook 与辅助程序 |-| [`Documents/`](README.md) | 设置、使用、兼容性和故障排查指南 |-| [`Research/`](../Research/README.md) | 补丁与实现研究记录 |+| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 虚拟机中的 hook 与辅助程序 |+| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad App 及其辅助程序 |++从源码构建:`xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`,产物为 `VPhone.bundle`。## 致谢diff --git a/README.md b/README.mdindex 327b6558..100dd111 100644--- a/README.md+++ b/README.md@@ -1,65 +1,120 @@-<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>+<div align="right"><a href="Documents/README.md">Docs</a> · <strong>English</strong> · <a href="Documents/README_zh.md">中文</a> · <a href="Documents/README_ja.md">日本語</a> · <a href="Documents/README_ko.md">한국어</a></div># vphone-cli-> Looking for vphone-cli 1.x? See the [1.0.14 release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14).--Create and run a virtual iPhone on an Apple Silicon Mac. vphone-cli uses Apple's Virtualization.framework and PCC research VM infrastructure.+Run a virtual iPhone on an Apple Silicon Mac.-Version 2.x applies the complete firmware patch set, including changes previously offered as EXP. There are no selectable patch variants. The self-contained `VPhone.bundle` handles firmware preparation, restore, and VM control; `vphone-launchpad` installs the bundle and guides you through creating and running a VM.+vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtual machines, for security research, reverse engineering, and debugging.++- **Graphical Window:** Use the virtual iPhone's screen on your Mac, browse apps and files, and take screenshots and screen recordings.+- **Custom Firmware:** The system comes pre-patched, and you can install a package environment.+- **Backup and Cloning:** You can export, import, and clone VMs.+- **Automation API:** An optional local HTTP and WebSocket interface.+- **No Extra Dependencies:** Needs no Xcode, Python, or Homebrew at runtime.++> For 1.x, see the [1.0.14 release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14). Version 2.x cannot start VMs created by 1.x. You need to create them again.++## Requirements++- A physical Apple Silicon Mac running macOS 15 or newer. It does not work in a macOS VM.+- Enough disk space. Each VM uses a 64 GB virtual disk by default, and firmware and temporary files take additional space.+- A network connection. Restoring the system fetches signing tickets online.+- Adjusted security settings. Boot into macOS Recovery, run these commands in Terminal, then restart:-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. Launchpad checks the host and uses its privileged helper to allow each verified VM binary through AMFI; see [host setup](Documents/Guides/host-setup.md) for details.+ ```sh+ csrutil enable --without debug+ csrutil allow-research-guests enable+ ```-## Get started+ SIP stays enabled, with only the debugging restrictions relaxed. For the reasons and other ways to set this up, see [Host Setup](Documents/Guides/host-setup.md).-Use the notarized [vphone-launchpad 2.1.2](https://github.com/Lakr233/vphone-cli/releases/download/2.1.2/vphone-launchpad-2.1.2-notarized.zip) on a physical Apple Silicon Mac running macOS 15 or newer. The release needs no Xcode, Python, or Homebrew at runtime.+## Get Started-1. In macOS Recovery, run `csrutil enable --without debug` and `csrutil allow-research-guests enable`, then restart. See [host setup](Documents/Guides/host-setup.md) for details.-2. Unzip and open the app. Complete **Host Setup**, including Developer Tools access and installation of the privileged helper.-3. In **Core Bundle**, choose **Download and Install** for the latest `VPhone.bundle`. Launchpad verifies the download and prepares its VM binary for the host.-4. In **Machines**, choose **New Machine**, select a firmware pairing from the catalog, and click **Create**. Launchpad completes the first-boot check and leaves the VM running.+1. Download the latest [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest) (`vphone-launchpad-<version>.zip`), unzip it, and open it.+2. In **Host Setup**, grant Developer Tools access and install the helper.+3. In **Core Bundle**, click **Download and Install**. Launchpad downloads and verifies `VPhone.bundle`, then allows the VM program inside it to run on your Mac.+4. In **Machines**, click **New Machine**, choose a firmware pairing, and click **Create**.-Catalog pairings download firmware. Creating a VM needs network access for restore tickets and substantial free disk space, even with local IPSWs. You can supply your own compatible iPhone and cloudOS IPSWs. See [compatibility](Documents/Guides/compatibility.md) for verified pairs. For source builds and terminal workflows, see [host setup](Documents/Guides/host-setup.md) and [create and run](Documents/Guides/create-and-run.md).+Launchpad downloads the firmware, patches it, restores the system, and boots it for the first time. When it finishes, the VM keeps running.-Version 2.x starts only VMs created with its `schemaVersion=2` format. Older VMs must be recreated.+You can also use your own iPhone and cloudOS IPSWs. For verified pairings, see [Compatibility](Documents/Guides/compatibility.md).-## Custom Firmware Bootstrap+## Install the Package Environment-After launching the VM, choose **Guest > Install Bootstrap…** from the macOS menu bar and select a layout. This installs Irisin in the guest.+The VM has no package manager by default. To install one:-For the first setup, select `apt` and `bash` in Irisin. Press and hold the **Install** button, then choose **Bootstrap Install**. This mode unpacks all packages in the installation before running the installation steps again. It resolves the initial dependency cycle where `debianutils` needs `bash`, but `bash` needs `debianutils` to have been configured. Use regular installation after this setup is complete.+1. In the menu bar, choose **Apps > Install Bootstrap…** and select the **roothide** layout (**rootless** is deprecated). This installs Irisin in the VM.+2. The first time, select `apt` and `bash` in Irisin, press and hold the install button, and choose **Bootstrap Install**. `bash` and `debianutils` depend on each other, so a normal install cannot complete.+3. After that, use a normal install.-## Everyday use+To remove the environment, choose **Apps > Uninstall Bootstrap…**. The VM restarts after removal.-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`. The VM prints a new API token at each launch as `[api] token: …`, or uses `VPHONE_API_TOKEN` when you set it. Send the token with every request, for example `curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health`. Requests without the token are refused, and so are requests from web pages. See the [guest API](Research/vphoned_http_api.md).+Hold Option while opening the **Apps** menu to see two more options:++- **Install Bootstrap from File…:** Installs from a local Irisin `.deb`.+- **Uninstall Bootstrap Without Restarting…:** Removes the environment without restarting the VM.++## Command Line++Launchpad manages VMs through the `vphone-cli` inside `VPhone.bundle`. You can also use it directly in Terminal:| Task | Command || --- | --- || List VMs | `vphone-cli vm list` |-| Inspect a VM | `vphone-cli vm info myphone` |-| Start the VM window | `vphone-cli vm launch myphone` |+| Show VM information | `vphone-cli vm info myphone` |+| Start a VM | `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` |+| Clone a VM | `vphone-cli vm clone myphone copy` |+| Export a VM | `vphone-cli vm export myphone --out myphone.tzst` |+| Import a VM | `vphone-cli vm import myphone.tzst --name restored` |++VMs are stored in `~/.vphone/` by default. Run `vphone-cli <group> --help` to see all commands. To create a VM without Launchpad, see [Create and Run](Documents/Guides/create-and-run.md).-VMs live under `~/.vphone/` by default. Run `vphone-cli <group> --help` for more commands.+### Automation API-## How it fits together+Add `--api-listen` at launch to turn it on:-`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`.+```sh+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765+# The output shows [api] token: …+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health+```-## Repository map+Each launch generates a new token. To use a fixed token, set the `VPHONE_API_TOKEN` environment variable. Requests without the token and requests from web pages are refused. For the interface reference, see the [API documentation](Research/vphoned_http_api.md).++## Troubleshooting++Start with [Troubleshooting](Documents/Guides/troubleshooting.md), which covers cases such as the system refusing the VM program, restore failures, and getting stuck on "Press home to continue". If that does not solve it, [open an issue](https://github.com/Lakr233/vphone-cli/issues).++## Documentation++| Document | Contents |+| --- | --- |+| [Host Setup](Documents/Guides/host-setup.md) | SIP and AMFI settings, building from source, environment checks |+| [Create and Run](Documents/Guides/create-and-run.md) | Firmware sources, the creation process, storage and backups |+| [Compatibility](Documents/Guides/compatibility.md) | Verified firmware pairings |+| [Troubleshooting](Documents/Guides/troubleshooting.md) | Common errors and how to fix them |+| [Launchpad Command Line](Documents/Guides/launchpad-cli.md) | Install and test a local build with `vphone-launchpad-cli` |+| [Research Notes](Research/README.md) | Patch and implementation details |++## Project Structure++- `vphone-launchpad`: A Mac app that downloads and installs `VPhone.bundle` and sets up the host. Released separately.+- `vphone-cli`: Prepares firmware, patches it, restores the system, and manages VMs.+- `vphone-vm`: Runs the VM and shows its window.+- `vphoned`: The control service inside the VM. The window's features and the API work through it.| Path | Contents || --- | --- |-| [`VPhoneExecutable/`](VPhoneExecutable/) | CLI, VM process, firmware patcher, and restore backend |+| [`VPhoneExecutable/`](VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, firmware patching and restore || [`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 |+| [`VPhoneDaemon/`](VPhoneDaemon/) | `vphoned` |+| [`VPhoneGuestComponents/`](VPhoneGuestComponents/) | Hooks and helper programs inside the VM |+| [`VPhoneLaunchpad/`](VPhoneLaunchpad/) | The Launchpad app and its helper |++To build from source, run `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`. The output is `VPhone.bundle`.## Acknowledgements