Run a virtual iPhone on an Apple Silicon Mac.
Swift
Document notarized Launchpad downloads and series matching
Lakr862ae0049059
diff --git a/AGENTS.md b/AGENTS.mdindex ab2183b3..fefbb58b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -59,6 +59,7 @@ The `VPhone` scheme puts host programs in `VPhone.bundle/Contents/MacOS` and eve- `vphone-cli` is the unentitled entry point. `VPhoneGuestLaunchPlanner` resolves `vphone-vm` beside the running executable, checks its entitlements, probes AMFI, and reports the exact allowlist command on refusal. It never obtains root itself.- `vphone-escalator` manages AMFI cdhash admission only. It writes amfid heap state, not executable code. Root authorization belongs to the user or to `vphone-launchpad`; neither `vphone-cli` nor the bundle has an SMJobBless or sudo password flow.- `vphone-launchpad` has no entitlements. It asks for Developer Tools access (`EPDeveloperTool`) and adds an `EPExecutionPolicy` exception for each installed bundle. Its helper is the only root surface: it installs verified releases into the root-owned store `/Library/Application Support/vphone-launchpad/Bundles`, runs that bundle's `vphone-escalator allow` for its receipt-pinned `vphone-vm`, and runs `cfw install` from that store after rechecking the recorded cdhash. There is no generic command verb. Nothing is signed at build time: `VPhoneLaunchpad/Build/SignLaunchpad.sh` signs afterwards, and the team comes from the gitignored `Configuration/Developer.xcconfig`. Never commit a team ID.+- Launchpad and `VPhone.bundle` match by series, the first two numbers of the version: Launchpad 2.2.3 works with any `VPhone.bundle` 2.2.x, and the reverse. Patch releases within a series must stay interchangeable in both directions. A change to anything Launchpad relies on in the bundle (`vphone-cli` arguments or output, `vphone-escalator`, the bundle layout or receipt) needs a new minor version and a raised `minimumBundleComponents` in `VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`. `Documents/Downloads/README.md` states this rule to users.- Host VM artifacts, caches, and archives created by vphone use mode `0777` for workstation access. Symlinks are not followed when changing permissions. Guest filesystem modes inside `Disk.img` remain unchanged.- `VPhoneRestore` runs in the CLI process over vendored libirecovery and idevicerestore. No Python or runtime Homebrew dependency is allowed.- The VM process owns AppKit windows and the guest control connection. `vphoned` serves HTTP and WebSocket over VSOCK 1339, with camera data on 1338.diff --git a/Documents/Downloads/README.md b/Documents/Downloads/README.mdnew file mode 100644index 00000000..6616d6df--- /dev/null+++ b/Documents/Downloads/README.md@@ -0,0 +1,37 @@+# Downloads++Each [release](https://github.com/Lakr233/vphone-cli/releases) has up to three files:++| File | Contents |+| --- | --- |+| `vphone-launchpad-<version>-notarized.zip` | Launchpad, signed and notarized by Apple. Download this one when it is available. |+| `vphone-launchpad-<version>.zip` | Launchpad, not notarized. macOS blocks it the first time you open it. |+| `VPhone-<version>.zip` | `VPhone.bundle`. Launchpad downloads and installs it for you, so you do not need this file. |++## Notarized Launchpad Versions++| Series | Notarized | Not Notarized |+| --- | --- | --- |+| 2.2 | 2.2.0, 2.2.2, 2.2.3 | 2.2.1 |+| 2.1 | 2.1.0, 2.1.1, 2.1.2 | 2.1.3, 2.1.4, 2.1.5, 2.1.6, 2.1.7 |+| 2.0 | 2.0.4, 2.0.5, 2.0.6, 2.0.8, 2.0.9 | — |++There is no 2.0.7 release.++To open a version that is not notarized, open it once, then go to **System Settings > Privacy & Security** and click **Open Anyway**.++## Matching Launchpad and VPhone.bundle++Use a `VPhone.bundle` from the same series as Launchpad. The series is the first two numbers of the version: Launchpad 2.2.3 belongs to 2.2 and works with any `VPhone.bundle` 2.2.x.++| Launchpad | VPhone.bundle |+| --- | --- |+| 2.2.x | 2.2.x |+| 2.1.x | 2.1.x |+| 2.0.x | 2.0.x |++Within a series, install the newest `VPhone.bundle`. Patch releases fix problems without changing how Launchpad and the bundle work together.++Launchpad refuses a `VPhone.bundle` that is too old for it, but it may still list bundles from a newer series. Do not install those; update Launchpad to that series first. Launchpad does not update itself: download the new version from the release page and replace the old app.++VMs created by 1.x do not start in 2.x. For 1.x, see the [1.0.14 release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14).diff --git a/Documents/Guides/package-environment.md b/Documents/Guides/package-environment.mdnew file mode 100644index 00000000..de554d6b--- /dev/null+++ b/Documents/Guides/package-environment.md@@ -0,0 +1,26 @@+# Package Environment++The VM has no package manager by default. To install one:++1. In the menu bar, choose **Apps > Install Bootstrap…** and select the **roothide** layout (**rootless** is deprecated). This installs Irisin in the VM.+2. For the first installation, select all of the following packages in Irisin at once, press and hold the install button, and choose **Bootstrap Install**:++ - `apt`+ - `bash`+ - `uikittools`+ - `launchctl`+ - `openssh-server`++ Install them together in one pass. Several of these packages depend on one another, and `openssh-server` declares some dependencies circularly, so installing them one by one can fail partway.+3. After the first installation, install further packages normally.++If the first installation fails, do not repair it in place. Choose **Apps > Uninstall Bootstrap…**, then start again from step 1.++## Remove the Environment++Choose **Apps > Uninstall Bootstrap…**. The VM restarts after removal.++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.diff --git a/Documents/README.md b/Documents/README.mdindex 830e52eb..8df09834 100644--- a/Documents/README.md+++ b/Documents/README.md@@ -1,25 +1,38 @@# Documentation-[Research notes](../Research/README.md)--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.+Start with the [Launchpad quick start](../README.md#get-started). For terminal use, see [Create and Run](Guides/create-and-run.md). Version 2.x applies the complete firmware patch set; there are no selectable patch variants.| Guide | Use it for || --- | --- |-| [Host setup](Guides/host-setup.md) | Apple Silicon, SIP/AMFI settings, signing and preflight |-| [Create and run a VM](Guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups |-| [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks actually prove |+| [Downloads](Downloads/README.md) | Notarized Launchpad versions and matching `VPhone.bundle` versions |+| [Host Setup](Guides/host-setup.md) | Apple Silicon, SIP and AMFI settings, signing and preflight |+| [Create and Run](Guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups |+| [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks prove |+| [Package Environment](Guides/package-environment.md) | Installing and removing a package manager in the VM || [Troubleshooting](Guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |+| [Launchpad Command Line](Guides/launchpad-cli.md) | Installing and testing a local build with `vphone-launchpad-cli` |## Translations[中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md)-These pages give a translated overview and quick start. The guides above hold the detailed, current procedures so that a change to the host or firmware flow has one place to update.+These pages give a translated overview and quick start. The guides above hold the current procedures.++## For Contributors-## For contributors+- `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.-- [Research index](../Research/README.md) groups the patch and implementation records by subject.-- [Patch inventory](../Research/0_binary_patch_comparison.md) is the canonical per-component comparison.-- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`; run each project's test scheme separately.-- `vphone-cli <group> --help` shows the CLI command surface.+| Path | Contents |+| --- | --- |+| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, firmware patching and restore |+| [`VPhoneKit/`](../VPhoneKit/) | Shared host libraries and API client |+| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | Hooks and helper programs inside the VM |+| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | The Launchpad app and its helper |++- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`. Run each project's test scheme separately.+- The [research index](../Research/README.md) groups patch and implementation records by subject.+- The [patch inventory](../Research/0_binary_patch_comparison.md) compares patches per component.diff --git a/Documents/README_ja.md b/Documents/README_ja.mdindex 26c07a69..59324e34 100644--- a/Documents/README_ja.md+++ b/Documents/README_ja.md@@ -32,7 +32,7 @@ vphone-cli は Apple の Virtualization.framework と PCC 研究用仮想マシ## クイックスタート-1. 最新の [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<バージョン>.zip`)をダウンロードし、展開して開きます。+1. [最新のリリース](https://github.com/Lakr233/vphone-cli/releases/latest)から `vphone-launchpad-<バージョン>-notarized.zip` をダウンロードし、展開して開きます。すべてのリリースが公証済みではありません。最新リリースに `-notarized` ファイルがない場合は、[ダウンロードガイド](Downloads/README.md)から公証済みのバージョンを選んでください。2. **Host Setup** で開発者ツールへのアクセスを許可し、ヘルパーをインストールします。3. **Core Bundle** で **Download and Install** をクリックします。Launchpad が `VPhone.bundle` をダウンロードして検証し、その中の仮想マシン用プログラムがこの Mac で実行できるようにします。4. **Machines** で **New Machine** をクリックし、ファームウェアの組み合わせを選んで **Create** をクリックします。@@ -102,6 +102,7 @@ token は起動のたびに新しく生成されます。token を固定する| ドキュメント | 内容 || --- | --- |+| [ダウンロードガイド](Downloads/README.md) | 公証済みの Launchpad バージョンと対応する `VPhone.bundle` バージョン || [ホストの設定](Guides/host-setup.md) | SIP と AMFI の設定、ソースからのビルド、環境の確認 || [作成と実行](Guides/create-and-run.md) | ファームウェアの入手元、作成の流れ、ストレージとバックアップ || [互換性ガイド](Guides/compatibility.md) | 検証済みのファームウェアの組み合わせ |diff --git a/Documents/README_ko.md b/Documents/README_ko.mdindex b401eb30..2c71d1b3 100644--- a/Documents/README_ko.md+++ b/Documents/README_ko.md@@ -32,7 +32,7 @@ vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 가상 머신## 빠른 시작-1. 최신 [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<버전>.zip`)를 내려받아 압축을 풀고 엽니다.+1. [최신 릴리스](https://github.com/Lakr233/vphone-cli/releases/latest)에서 `vphone-launchpad-<버전>-notarized.zip`을 내려받아 압축을 풀고 엽니다. 모든 릴리스가 공증된 것은 아닙니다. 최신 릴리스에 `-notarized` 파일이 없으면 [다운로드 안내](Downloads/README.md)에서 공증된 버전을 선택하세요.2. **Host Setup**에서 개발자 도구 권한을 부여하고 도우미 프로그램을 설치합니다.3. **Core Bundle**에서 **Download and Install**을 클릭합니다. Launchpad가 `VPhone.bundle`을 내려받아 검증한 뒤, 그 안의 가상 머신 프로그램이 이 Mac에서 실행되도록 허용합니다.4. **Machines**에서 **New Machine**을 클릭하고 펌웨어 조합을 선택한 뒤 **Create**를 클릭합니다.@@ -102,6 +102,7 @@ curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health| 문서 | 내용 || --- | --- |+| [다운로드 안내](Downloads/README.md) | 공증된 Launchpad 버전과 맞는 `VPhone.bundle` 버전 || [호스트 설정](Guides/host-setup.md) | SIP 및 AMFI 설정, 소스 빌드, 환경 점검 || [생성 및 실행](Guides/create-and-run.md) | 펌웨어 출처, 생성 절차, 저장과 백업 || [호환성 안내](Guides/compatibility.md) | 검증된 펌웨어 조합 |diff --git a/Documents/README_zh.md b/Documents/README_zh.mdindex 6b6a953b..ec3f5261 100644--- a/Documents/README_zh.md+++ b/Documents/README_zh.md@@ -32,7 +32,7 @@ vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机运## 快速开始-1. 下载最新的 [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest)(`vphone-launchpad-<版本>.zip`),解压并打开。+1. 从[最新 release](https://github.com/Lakr233/vphone-cli/releases/latest)下载 `vphone-launchpad-<版本>-notarized.zip`,解压并打开。并非每个 release 都经过公证。如果最新版本没有 `-notarized` 文件,请在[下载说明](Downloads/README.md)中选择一个已公证的版本。2. 在 **Host Setup** 中授予开发者工具权限,并安装辅助程序。3. 在 **Core Bundle** 中点击 **Download and Install**。Launchpad 会下载并校验 `VPhone.bundle`,然后允许其中的虚拟机程序在本机运行。4. 在 **Machines** 中点击 **New Machine**,选择一组固件,点击 **Create**。@@ -102,6 +102,7 @@ curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health| 文档 | 内容 || --- | --- |+| [下载说明](Downloads/README.md) | 已公证的 Launchpad 版本及匹配的 `VPhone.bundle` 版本 || [宿主机设置](Guides/host-setup.md) | SIP 与 AMFI 设置、源码构建、环境检查 || [创建与运行](Guides/create-and-run.md) | 固件来源、创建流程、存储与备份 || [兼容性说明](Guides/compatibility.md) | 已验证的固件组合 |diff --git a/README.md b/README.mdindex 39a88ff5..14cd05f9 100644--- a/README.md+++ b/README.md@@ -14,12 +14,10 @@ vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtu- **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.+- Free disk space. Each VM has a 64 GB virtual disk by default, and firmware takes more.- A network connection. Restoring the system fetches signing tickets online.- Adjusted security settings. Boot into macOS Recovery, run these commands in Terminal, then restart:@@ -28,103 +26,47 @@ vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtucsrutil allow-research-guests enable```- 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).+ SIP stays enabled, with only the debugging restrictions relaxed. For details, see [Host Setup](Documents/Guides/host-setup.md).## Get Started-1. Download the latest [vphone-launchpad](https://github.com/Lakr233/vphone-cli/releases/latest) (`vphone-launchpad-<version>.zip`), unzip it, and open it.+1. Download `vphone-launchpad-<version>-notarized.zip` from the [latest release](https://github.com/Lakr233/vphone-cli/releases/latest), unzip it, and open it. Not every release is notarized. If the latest one has no `-notarized` file, pick a notarized version from [Downloads](Documents/Downloads/README.md).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.+3. In **Core Bundle**, click **Download and Install**.4. In **Machines**, click **New Machine**, choose a firmware pairing, and click **Create**.-Launchpad downloads the firmware, patches it, restores the system, and boots it for the first time. When it finishes, the VM keeps running.--You can also use your own iPhone and cloudOS IPSWs. For verified pairings, see [Compatibility](Documents/Guides/compatibility.md).--## Install the Package Environment--The VM has no package manager by default. To install one:--1. In the menu bar, choose **Apps > Install Bootstrap…** and select the **roothide** layout (**rootless** is deprecated). This installs Irisin in the VM.-2. For the first installation, select all of the following packages in Irisin at once, press and hold the install button, and choose **Bootstrap Install**:-- - `apt`- - `bash`- - `uikittools`- - `launchctl`- - `openssh-server`-- Installing them together in one bootstrap pass is recommended. Several of these packages depend on one another (for example, `bash` and `debianutils`), and `openssh-server` in particular declares some dependencies circularly or imprecisely, so installing them one by one with a normal install can fail partway.-3. After the first installation, install further packages normally.--If the first installation fails or leaves the environment in an inconsistent state, do not attempt to repair it in place. Remove the environment with **Apps > Uninstall Bootstrap…** and install it again from step 1.--To remove the environment, choose **Apps > Uninstall Bootstrap…**. The VM restarts after removal.--Hold Option while opening the **Apps** menu to see two more options:+Launchpad downloads the firmware, patches it, restores the system, and boots the VM. To use your own iPhone and cloudOS IPSWs, see [Compatibility](Documents/Guides/compatibility.md).-- **Install Bootstrap from File…:** Installs from a local Irisin `.deb`.-- **Uninstall Bootstrap Without Restarting…:** Removes the environment without restarting the VM.+To install a package manager in the VM, see [Package Environment](Documents/Guides/package-environment.md).## 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` |-| Show VM information | `vphone-cli vm info myphone` |-| Start a VM | `vphone-cli vm launch myphone` |-| Stop a VM | `vphone-cli vm stop myphone` |-| 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).--### Automation API--Add `--api-listen` at launch to turn it on:+Launchpad drives VMs through the `vphone-cli` inside `VPhone.bundle`. You can also run it in Terminal:```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+vphone-cli vm list+vphone-cli vm launch myphone+vphone-cli vm export myphone --out myphone.tzst```-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).+VMs are stored in `~/.vphone/`. 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).-## 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).+To turn on the automation API, add `--api-listen 127.0.0.1:8765` at launch and use the token it prints. See the [API documentation](Research/vphoned_http_api.md).## Documentation| Document | Contents || --- | --- |+| [Downloads](Documents/Downloads/README.md) | Notarized Launchpad versions and matching `VPhone.bundle` versions || [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 |+| [Package Environment](Documents/Guides/package-environment.md) | Installing and removing a package manager in the VM || [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/) | `vphone-cli`, `vphone-vm`, firmware patching and restore |-| [`VPhoneKit/`](VPhoneKit/) | Shared host libraries and API client |-| [`VPhoneDaemon/`](VPhoneDaemon/) | `vphoned` |-| [`VPhoneGuestComponents/`](VPhoneGuestComponents/) | Hooks and helper programs inside the VM |-| [`VPhoneLaunchpad/`](VPhoneLaunchpad/) | The Launchpad app and its helper |+| [Contributing](Documents/README.md#for-contributors) | Project structure, building from source, research notes |-To build from source, run `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`. The output is `VPhone.bundle`.+If these do not solve your problem, [open an issue](https://github.com/Lakr233/vphone-cli/issues).## Acknowledgements