Skip to content

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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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 virtu
csrutil 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