Run a virtual iPhone on an Apple Silicon Mac.
Swift
docs: recommend Launchpad for 2.0.4 setup
Lakr2290c7be134f
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.mdindex 98f70771..250acbfb 100644--- a/Documents/Guides/create-and-run.md+++ b/Documents/Guides/create-and-run.md@@ -2,7 +2,7 @@[Documentation](../README.md) · [Host setup](host-setup.md) · [Compatibility](compatibility.md)-The public firmware workflow creates one **JB** configuration. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.+The public firmware workflow applies one complete patch set, including the former EXP changes; patch variants cannot be selected. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.## One-command flow@@ -15,7 +15,7 @@ vphone-cli vm create myphone \--cloudos-source /path/to/cloudOS.ipsw```-Creation runs prepare → JB patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. The caller must provide root privileges for CFW installation; this bundle has no authorization dialog or privilege helper. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.+Creation runs prepare → firmware patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. The caller must provide root privileges for CFW installation; this bundle has no authorization dialog or privilege helper. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.`fw prepare` creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.diff --git a/Documents/README.md b/Documents/README.mdindex 3a33daae..830e52eb 100644--- a/Documents/README.md+++ b/Documents/README.md@@ -2,7 +2,7 @@[Research notes](../Research/README.md)-Start with the [one-command VM flow](Guides/create-and-run.md). The guides below describe the current **JB-only** CLI. Older patch variants and installation experiments remain in research notes as historical context, not supported user workflows.+Start with the [Launchpad quick start](../README.md#get-started). For terminal use, see the [one-command VM flow](Guides/create-and-run.md). Version 2.x applies the complete firmware patch set, including the former EXP changes; selectable patch variants are not available. Earlier experiments remain in the research notes as historical context.| Guide | Use it for || --- | --- |diff --git a/Documents/README_ja.md b/Documents/README_ja.mdindex 7e8b66dd..d9de3ad5 100644--- a/Documents/README_ja.md+++ b/Documents/README_ja.md@@ -2,37 +2,26 @@# vphone-cli-> [!WARNING]-> バージョン 2.0 は開発中です。安定版が必要な場合は [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14) を使用してください。+> 旧バージョンの 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 基盤を使用します。-バージョン 2.0 では、1.0 の負担が大きく複雑なホスト設定を大幅に減らし、カスタムファームウェアに必要なシステム修正を整理しました。基本の流れが安定してきたため、構成は **JB の 1 種類**に絞っています。自己完結した `VPhone.bundle` の CLI から、ファームウェアのダウンロード、インストール、起動まで行えます。+バージョン 2.x では、以前 EXP として提供していた変更を含む、ファームウェアの完全なパッチセットを適用します。パッチ構成は選択できません。自己完結した `VPhone.bundle` がファームウェアの準備、復元、VM の制御を担い、`vphone-launchpad` が bundle のインストールと VM の作成・起動を案内します。-現時点で推奨するホスト設定は、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` ではセットアップを簡単にし、インストール時の修正を切り替えられるようにする予定です。+推奨するホスト設定では、macOS 復旧環境で `csrutil enable --without debug` と `csrutil allow-research-guests enable` を実行します。SIP を有効に保ちつつ、デバッグの制限を緩和します。Launchpad はホストを確認し、特権ヘルパーを使用して検証済みの VM バイナリを AMFI に許可します。詳しくは[ホストの設定](Guides/host-setup.md)をご覧ください。## はじめに-macOS 15 以降の Apple Silicon Mac、ソースからのビルドに使う Xcode、iPhone の復元 IPSW、互換性のある cloudOS IPSW が必要です。[ホストの設定](Guides/host-setup.md)で VM に必要なプライベート権限を許可し、[検証済みのファームウェアの組み合わせ](Guides/compatibility.md)を確認してください。macOS VM の中でゲストを動かすことはできません。+macOS 15 以降を搭載した物理 Apple Silicon Mac では、公証済みの [vphone-launchpad 2.0.4](https://github.com/Lakr233/vphone-cli/releases/download/2.0.4/vphone-launchpad-2.0.4-notarized.zip) を使用してください。リリース版の実行に Xcode、Python、Homebrew は不要です。-```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"+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 は実行されたままです。-vphone-cli host preflight-vphone-cli vm create myphone \- --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw-vphone-cli vm launch myphone-```--`vm create` はゲストの準備と復元、JB システム変更の導入、`vphoned` の応答確認を行います。確認用の起動は完了後に停止します。使用するには `vm launch` で VM ウィンドウを開いてください。作成にはネットワーク接続、CFW のインストールには管理者権限が必要です。詳しくは[作成と起動のガイド](Guides/create-and-run.md)を参照してください。+カタログの組み合わせを選ぶと、ファームウェアがダウンロードされます。ローカルの IPSW を使う場合も、VM の作成には復元チケット取得のためのネットワーク接続と十分な空き容量が必要です。互換性のある iPhone と cloudOS の IPSW を自分で指定することもできます。検証済みの組み合わせは[互換性ガイド](Guides/compatibility.md)をご覧ください。ソースからのビルドとターミナルでの操作は[ホストの設定](Guides/host-setup.md)と[作成と起動のガイド](Guides/create-and-run.md)を参照してください。2.x 版で起動できるのは `schemaVersion=2` 形式で作成された VM だけです。旧版の VM は作り直す必要があります。diff --git a/Documents/README_ko.md b/Documents/README_ko.mdindex e6adb48b..86bf1f06 100644--- a/Documents/README_ko.md+++ b/Documents/README_ko.md@@ -2,37 +2,26 @@# vphone-cli-> [!WARNING]-> 버전 2.0은 개발 중입니다. 안정 버전이 필요하면 [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14)를 사용하세요.+> 이전 버전의 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 기반을 사용합니다.-버전 2.0에서는 1.0의 무겁고 복잡한 호스트 설정을 상당 부분 없애고 커스텀 펌웨어에 필요한 시스템 수정 사항을 간소화했습니다. 핵심 흐름이 어느 정도 안정되어 구성은 **JB 한 가지**로 정리했습니다. 독립적으로 실행 가능한 `VPhone.bundle`의 CLI에서 펌웨어 다운로드부터 설치와 시작까지 처리합니다.+버전 2.x는 이전에 EXP로 제공하던 변경 사항을 포함한 전체 펌웨어 패치 세트를 적용합니다. 패치 구성은 선택할 수 없습니다. 독립적으로 실행 가능한 `VPhone.bundle`이 펌웨어 준비, 복원, VM 제어를 담당하고, `vphone-launchpad`가 bundle 설치와 VM 생성 및 실행을 안내합니다.-현재 권장하는 호스트 설정은 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`에서는 설정을 더 쉽게 하고 설치 단계의 수정 사항을 선택할 수 있게 할 예정입니다.+권장 호스트 설정은 macOS 복구 환경에서 `csrutil enable --without debug`와 `csrutil allow-research-guests enable`을 실행하는 것입니다. SIP를 켠 상태로 유지하면서 디버깅 제한을 완화합니다. Launchpad는 호스트를 확인하고 권한 있는 도우미를 사용하여 검증된 VM 바이너리가 AMFI를 통과하도록 허용합니다. 자세한 내용은 [호스트 설정](Guides/host-setup.md)을 참고하세요.## 시작하기-macOS 15 이상이 설치된 Apple Silicon Mac, 소스 빌드용 Xcode, iPhone 복원 IPSW, 호환되는 cloudOS IPSW가 필요합니다. [호스트 설정](Guides/host-setup.md)에 따라 VM의 비공개 권한을 허용하고 [검증된 펌웨어 조합](Guides/compatibility.md)을 확인하세요. 중첩된 macOS VM에서는 게스트를 실행할 수 없습니다.+macOS 15 이상을 실행하는 물리 Apple Silicon Mac에서는 공증된 [vphone-launchpad 2.0.4](https://github.com/Lakr233/vphone-cli/releases/download/2.0.4/vphone-launchpad-2.0.4-notarized.zip)를 사용하세요. 릴리스 버전을 실행할 때 Xcode, Python, Homebrew는 필요하지 않습니다.-```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"+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은 계속 실행됩니다.-vphone-cli host preflight-vphone-cli vm create myphone \- --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw-vphone-cli vm launch myphone-```--`vm create`는 게스트 준비와 복원, JB 시스템 변경 설치, `vphoned` 응답 확인을 수행합니다. 확인용 부팅은 완료 후 중지되므로, 실제 사용을 위해 `vm launch`로 VM 창을 여세요. 생성에는 네트워크 연결이, CFW 설치에는 관리자 권한이 필요합니다. 자세한 내용은 [생성 및 실행 가이드](Guides/create-and-run.md)를 참고하세요.+카탈로그의 펌웨어 조합을 선택하면 펌웨어가 다운로드됩니다. 로컬 IPSW를 사용하더라도 VM을 생성하려면 복원 티켓을 받을 네트워크 연결과 충분한 디스크 여유 공간이 필요합니다. 호환되는 iPhone 및 cloudOS IPSW를 직접 지정할 수도 있습니다. 검증된 조합은 [호환성 가이드](Guides/compatibility.md)를 참고하세요. 소스 빌드와 터미널 사용법은 [호스트 설정](Guides/host-setup.md) 및 [생성 및 실행 가이드](Guides/create-and-run.md)를 확인하세요.2.x 버전은 `schemaVersion=2` 형식으로 생성한 VM만 시작할 수 있습니다. 이전 버전의 VM은 다시 만들어야 합니다.diff --git a/Documents/README_zh.md b/Documents/README_zh.mdindex 4b6797e9..ecfe9bb0 100644--- a/Documents/README_zh.md+++ b/Documents/README_zh.md@@ -2,37 +2,26 @@# vphone-cli-> [!WARNING]-> 2.0 版仍在开发中。需要稳定版本请使用 [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14)。+> 查找旧版 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 研究虚拟机基础设施。-2.0 移除了 1.0 中不少繁重的宿主机环境配置,也精简了定制固件所需的系统修复。目前核心流程已趋于稳定,因此只保留一套 **JB** 配置:自包含的 `VPhone.bundle` 通过其中的 CLI 完成固件下载、安装和启动。+2.x 会应用完整的固件补丁集,包含此前作为 EXP 提供的改动;目前不能选择不同的补丁方案。自包含的 `VPhone.bundle` 负责固件准备、恢复和虚拟机控制;`vphone-launchpad` 负责安装 bundle,并引导你创建和运行虚拟机。-目前推荐在 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` 会简化设置,并提供安装阶段修复项的开关。+推荐在 macOS 恢复模式中执行 `csrutil enable --without debug` 和 `csrutil allow-research-guests enable`。这样会保留 SIP,但放宽调试限制。Launchpad 会检查宿主机,并通过特权辅助程序让 AMFI 放行已验证的虚拟机程序;详见[宿主机设置](Guides/host-setup.md)。## 开始使用-需要运行 macOS 15 或更新版本的 Apple Silicon Mac、用于源码构建的 Xcode、iPhone 恢复 IPSW,以及兼容的 cloudOS IPSW。先按[宿主机设置](Guides/host-setup.md)允许虚拟机所需的私有授权,并查看[已验证的固件组合](Guides/compatibility.md)。不能在嵌套的 macOS 虚拟机中运行访客系统。+推荐在运行 macOS 15 或更新版本的实体 Apple Silicon Mac 上使用已公证的 [vphone-launchpad 2.0.4](https://github.com/Lakr233/vphone-cli/releases/download/2.0.4/vphone-launchpad-2.0.4-notarized.zip)。运行发布版无需 Xcode、Python 或 Homebrew。-```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"+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 完成首次启动检查后,虚拟机会保持运行。-vphone-cli host preflight-vphone-cli vm create myphone \- --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw-vphone-cli vm launch myphone-```--`vm create` 准备和恢复访客系统、安装 JB 系统改动,并确认 `vphoned` 能响应。验证完成后,它会停止本次启动;执行 `vm launch` 才会打开供日常使用的虚拟机窗口。创建过程需要网络,安装 CFW 需要管理员权限。详见[创建与运行指南](Guides/create-and-run.md)。+选择目录中的固件组合时会下载固件。即使使用本地 IPSW,创建虚拟机仍需联网获取恢复票据,并留出充足的磁盘空间。也可以自行提供兼容的 iPhone 和 cloudOS IPSW;已验证的组合见[兼容性说明](Guides/compatibility.md)。源码构建和命令行操作见[宿主机设置](Guides/host-setup.md)与[创建与运行指南](Guides/create-and-run.md)。2.x 版只能启动以 `schemaVersion=2` 格式创建的虚拟机。旧版虚拟机需要重新创建。diff --git a/README.md b/README.mdindex c63eab86..01726445 100644--- a/README.md+++ b/README.md@@ -2,37 +2,26 @@# vphone-cli-> [!WARNING]-> Version 2.0 is under construction. For the stable version, use [1.0.14](https://github.com/Lakr233/vphone-cli/tree/1.0.14).+> 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.-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.+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.-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.+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.## Get started-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.+Use the notarized [vphone-launchpad 2.0.4](https://github.com/Lakr233/vphone-cli/releases/download/2.0.4/vphone-launchpad-2.0.4-notarized.zip) on a physical Apple Silicon Mac running macOS 15 or newer. The release needs no Xcode, Python, or Homebrew at runtime.-```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"+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.-vphone-cli host preflight-vphone-cli vm create myphone \- --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw-vphone-cli vm launch myphone-```--`vm create` 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.+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).Version 2.x starts only VMs created with its `schemaVersion=2` format. Older VMs must be recreated.