Skip to content

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.md
index 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 を実行します。
![macOS 上で動作する仮想 iPhone](demo.jpeg)
-バージョン 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.md
index 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을 실행합니다.
![macOS에서 실행 중인 가상 iPhone](demo.jpeg)
-버전 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.md
index 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。
![在 macOS 上运行的虚拟 iPhone](demo.jpeg)
-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.md
index 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.
![Virtual iPhone running on macOS](Documents/demo.jpeg)
-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