trending/vphone-cli
1
0
Fork 0
mirror of https://github.com/Lakr233/vphone-cli.git synced 2026-10-02 08:04:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document notarized Launchpad downloads and series matching

Browse Source 
Add Documents/Downloads/README.md listing which 2.x Launchpad releases
ship a notarized zip, and the rule that Launchpad x.y works with any
VPhone.bundle x.y.z. Record the same rule in AGENTS.md: patch releases
within a series stay interchangeable both ways.

Slim README.md: move the package environment steps into
Documents/Guides/package-environment.md and the project structure into
Documents/README.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Lakr
2026-10-01 11:13:18 +09:00
co-authored by Claude Opus 5.5
parent a34e5511d4
commit 862ae00490
8 changed files with 111 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+1
View File
@@ -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.
Documents/Downloads/README.md
+37
View File
@@ -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).
Documents/Guides/package-environment.md
+26
View File
@@ -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.
Documents/README.md
+25 -12
View File
@@ -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
- [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.
- `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 |
- `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.
Documents/README_ja.md
+2 -1
View File
@@ -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) | 検証済みのファームウェアの組み合わせ |
Documents/README_ko.md
+2 -1
View File
@@ -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) | 검증된 펌웨어 조합 |
Documents/README_zh.md
+2 -1
View File
@@ -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) | 已验证的固件组合 |
README.md
+16 -74
View File
@@ -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.
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).
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:
- **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 |
| [Contributing](Documents/README.md#for-contributors) | Project structure, building from source, research notes |
## 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 |
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