Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat(vm create): prompt for firmware pairing when a source is omitted

zqxwcee490a2aaf8f2
diff --git a/README.md b/README.md
index 074ee6f3..f12eac35 100644
--- a/README.md
+++ b/README.md
@@ -71,10 +71,10 @@ csrutil allow-research-guests enable
Then reboot into macOS and allowlist the repo with [`amfidont`](https://github.com/zqxwce/amfidont) (or [`amfree`](https://github.com/retX0/amfree)):
```bash
-sudo amfidont --path <repo>
+sudo amfidont --path <path_to_vphone-cli.app>
```
-> The `less` (patchless) variant needs Option A, or Option B with `amfidont -S` (`sudo amfidont -S --path <repo>`).
+> The `less` (patchless) variant needs Option A, or Option B with `amfidont -S` (`sudo amfidont -S --path <path_to_vphone-cli.app>`).
**Dependencies:**
@@ -97,7 +97,7 @@ Two one-time bootstrap scripts (a compiled binary can't build itself), then ever
Put the binary on your `PATH` so the examples below work verbatim:
```bash
-cd .build/release
+cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -109,7 +109,7 @@ One command creates a VM end-to-end (download → patch → DFU restore → CFW
vphone-cli vm create myphone -V jb # -V / --variant
```
-With no source flags it downloads a default tested iPhone + cloudOS pair. To choose specific firmware, pass **`-i`/`--iphone-source`** and **`-c`/`--cloudos-source`** — each takes either a **URL** or a **local `.ipsw` path** (see [Tested Environments](#tested-environments) for known-good pairs):
+The user is then prompted to choose iOS <-> cloudOS paring, you can specify either one by passing **`-i`/`--iphone-source`** and/or **`-c`/`--cloudos-source`**, i.e.:
```bash
# from local IPSWs
@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \
# or from URLs — downloaded and cached under ~/.vphone/ipsws
vphone-cli vm create myphone -V jb \
- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"
+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
+ -c "https://.../399b6..."
```
-The CFW-install stage needs root (host disk mount) and will prompt for `sudo`; pass `-s <pw>` (`--sudo-password`) to run unattended. Add `-v` to watch the restore (pmd3 log, colorized), `-vv` for pmd3 debug detail, `-vvv` for vphone-cli's internal trace. Then boot it:
+Then boot it:
```bash
vphone-cli vm launch myphone
```
-VMs live in a **library** at `~/.vphone/VMs/` (override any command with `--library-root <dir>`). Run any VM command with no name (e.g. `vphone-cli vm launch`) to pick from a menu of your VMs.
-
## Commands
`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.
@@ -187,6 +185,18 @@ without the repo. Provisioning is automatic; run `vphone-cli setup` to do it
up front. Point at a specific interpreter with `VPHONE_PYTHON=/path/to/python3`,
or relocate the venv with `VPHONE_VENV_DIR=/path`.
+## Locations
+
+Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable:
+
+| Path | Contents |
+| ----------------- | -------------------------------------------------------------------------------------------- |
+| `~/.vphone/VMs/` | VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`. |
+| `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. |
+| `~/.vphone/tools/`| Cached APFS seal-volume artifacts (`apfs_sealvolume_<version>`) fetched during `fw prepare`. |
+| `~/.vphone/debs/` | Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …). |
+| `~/.vphone/venv/` | Auto-provisioned Python environment (see [Python runtime](#python-runtime); override with `$VPHONE_VENV_DIR`). |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1` or `amfidont`).
diff --git a/docs/README_ja.md b/docs/README_ja.md
index 1dd4bd4b..25eeb611 100644
--- a/docs/README_ja.md
+++ b/docs/README_ja.md
@@ -71,10 +71,10 @@ csrutil allow-research-guests enable
その後 macOS で再起動し、[`amfidont`](https://github.com/zqxwce/amfidont)(または [`amfree`](https://github.com/retX0/amfree))でリポジトリを許可リストに追加します:
```bash
-sudo amfidont --path <repo>
+sudo amfidont --path <path_to_vphone-cli.app>
```
-> `less`(パッチなし)バリアントにはオプション A、またはオプション B に `amfidont -S` を組み合わせたもの(`sudo amfidont -S --path <repo>`)が必要です。
+> `less`(パッチなし)バリアントにはオプション A、またはオプション B に `amfidont -S` を組み合わせたもの(`sudo amfidont -S --path <path_to_vphone-cli.app>`)が必要です。
**依存関係:**
@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key
以下の例をそのまま実行できるように、バイナリを `PATH` に追加します:
```bash
-cd .build/release
+cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -109,7 +109,7 @@ vphone-cli --help
vphone-cli vm create myphone -V jb # -V / --variant
```
-ソースフラグを指定しない場合、動作確認済みのデフォルトの iPhone + cloudOS ペアがダウンロードされます。特定のファームウェアを選ぶには **`-i`/`--iphone-source`** と **`-c`/`--cloudos-source`** を渡します — それぞれ **URL** または **ローカルの `.ipsw` パス** のいずれかを取ります(既知の良好なペアについては [動作確認済み環境](#動作確認済み環境) を参照):
+その後、iOS <-> cloudOS のペアリングを選ぶよう促されます。**`-i`/`--iphone-source`** および/または **`-c`/`--cloudos-source`** を渡して、どちらか(または両方)を指定することもできます。例:
```bash
# ローカルの IPSW から
@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \
# または URL から — ~/.vphone/ipsws 以下にダウンロードしてキャッシュ
vphone-cli vm create myphone -V jb \
- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"
+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
+ -c "https://.../399b6..."
```
-CFW インストール段階は root 権限(ホストディスクのマウント)が必要で、`sudo` の入力を求めます。無人で実行するには `-s <pw>`(`--sudo-password`)を渡します。復元の様子を見るには `-v`(pmd3 ログ、カラー表示)、pmd3 のデバッグ詳細には `-vv`、vphone-cli の内部トレースには `-vvv` を追加します。その後、起動します:
+その後、起動します:
```bash
vphone-cli vm launch myphone
```
-VM は `~/.vphone/VMs/` にある **ライブラリ** に保存されます(任意のコマンドで `--library-root <dir>` によって上書き可能)。VM コマンドを名前なしで実行すると(例: `vphone-cli vm launch`)、VM のメニューから選択できます。
-
## コマンド
`vphone-cli vm create` はパイプライン全体を実行します。以下の個別ステップを使うと、手動で操作したり 1 つの段階を再実行したりできます。
@@ -181,6 +179,18 @@ vphone-cli vm launch myphone # 6. 初回起動
いくつかのステップ(DFU 復元、IPSW 処理)は Python を通じて実行されます。初回使用時、vphone-cli はバンドルされた `requirements.txt` を使用して、最新のホスト `python3`(3.11+)から `~/.vphone/venv` に自己完結型の venv をプロビジョニングします — そのため署名済みの `.app` は **ポータブル** です。任意の場所(例: `/Applications`)にコピーすればリポジトリなしで動作します。プロビジョニングは自動ですが、事前に行うには `vphone-cli setup` を実行します。特定のインタプリタを指定するには `VPHONE_PYTHON=/path/to/python3`、venv の場所を変更するには `VPHONE_VENV_DIR=/path` を使用します。
+## 場所
+
+vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと `.app` の外に保管されます:
+
+| パス | 内容 |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。ライブラリであり、`$VPHONE_LIBRARY_ROOT` で上書きできます。 |
+| `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 |
+| `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 |
+| `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 |
+| `~/.vphone/venv/` | 自動的にプロビジョニングされる Python 環境([Python ランタイム](#python-ランタイム) を参照。`$VPHONE_VENV_DIR` で上書き可能)。 |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/デバッグ制限がバイパスされていません。[前提条件](#前提条件) を参照してください(`amfi_get_out_of_my_way=1` または `amfidont`)。
diff --git a/docs/README_ko.md b/docs/README_ko.md
index e4cf8986..fbaec127 100644
--- a/docs/README_ko.md
+++ b/docs/README_ko.md
@@ -71,10 +71,10 @@ csrutil allow-research-guests enable
그런 다음 macOS로 재부팅하고 [`amfidont`](https://github.com/zqxwce/amfidont) (또는 [`amfree`](https://github.com/retX0/amfree))로 저장소를 허용 목록에 추가합니다:
```bash
-sudo amfidont --path <repo>
+sudo amfidont --path <path_to_vphone-cli.app>
```
-> `less` (patchless) 변형은 방법 A, 또는 `amfidont -S`를 포함한 방법 B(`sudo amfidont -S --path <repo>`)가 필요합니다.
+> `less` (patchless) 변형은 방법 A, 또는 `amfidont -S`를 포함한 방법 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)가 필요합니다.
**의존성:**
@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key
아래 예제가 그대로 작동하도록 바이너리를 `PATH`에 추가하세요:
```bash
-cd .build/release
+cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -109,7 +109,7 @@ vphone-cli --help
vphone-cli vm create myphone -V jb # -V / --variant
```
-소스 플래그가 없으면 기본적으로 테스트된 iPhone + cloudOS 쌍을 다운로드합니다. 특정 펌웨어를 선택하려면 **`-i`/`--iphone-source`**와 **`-c`/`--cloudos-source`**를 전달하세요 — 각각 **URL** 또는 **로컬 `.ipsw` 경로**를 받습니다 (검증된 쌍은 [테스트 환경](#테스트-환경)을 참조하세요):
+그러면 iOS <-> cloudOS 페어링을 선택하라는 안내가 표시됩니다. **`-i`/`--iphone-source`** 및/또는 **`-c`/`--cloudos-source`**를 전달하여 둘 중 하나(또는 둘 다)를 직접 지정할 수도 있습니다. 예:
```bash
# 로컬 IPSW에서
@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \
# 또는 URL에서 — 다운로드되어 ~/.vphone/ipsws 아래에 캐시됨
vphone-cli vm create myphone -V jb \
- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"
+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
+ -c "https://.../399b6..."
```
-CFW 설치 단계는 root(호스트 디스크 마운트)가 필요하며 `sudo`를 요청합니다; 무인 실행을 위해서는 `-s <pw>`(`--sudo-password`)를 전달하세요. 복원 과정을 보려면 `-v`(pmd3 로그, 색상 표시), pmd3 디버그 상세 정보는 `-vv`, vphone-cli의 내부 추적은 `-vvv`를 추가하세요. 그런 다음 부팅합니다:
+그런 다음 부팅합니다:
```bash
vphone-cli vm launch myphone
```
-VM은 `~/.vphone/VMs/`의 **라이브러리**에 저장됩니다 (어떤 명령이든 `--library-root <dir>`로 재정의할 수 있습니다). 이름 없이 VM 명령을 실행하면 (예: `vphone-cli vm launch`) VM 목록 메뉴에서 선택할 수 있습니다.
-
## 명령어
`vphone-cli vm create`는 전체 파이프라인을 실행합니다; 아래 개별 단계들을 사용하면 수동으로 진행하거나 한 단계만 다시 실행할 수 있습니다.
@@ -187,6 +185,18 @@ vphone-cli는 번들된 `requirements.txt`를 사용하여 최신 호스트 `pyt
실행하세요. 특정 인터프리터를 지정하려면 `VPHONE_PYTHON=/path/to/python3`을,
venv 위치를 변경하려면 `VPHONE_VENV_DIR=/path`를 사용하세요.
+## 위치
+
+vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 `.app` 외부에 보관됩니다:
+
+| 경로 | 내용 |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `~/.vphone/VMs/` | VM 번들 — VM마다 하나의 디렉터리. 라이브러리이며, `$VPHONE_LIBRARY_ROOT`로 재정의할 수 있습니다. |
+| `~/.vphone/ipsws/`| 다운로드된 iPhone + cloudOS IPSW, 캐시되어 여러 VM에서 재사용됩니다. |
+| `~/.vphone/tools/`| `fw prepare` 중에 가져온 APFS seal-volume 아티팩트(`apfs_sealvolume_<version>`) 캐시. |
+| `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). |
+| `~/.vphone/venv/` | 자동으로 프로비저닝되는 Python 환경 ([Python 런타임](#python-런타임) 참조; `$VPHONE_VENV_DIR`로 재정의). |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/디버그 제한이 우회되지 않았습니다; [사전 요구 사항](#사전-요구-사항)을 참조하세요 (`amfi_get_out_of_my_way=1` 또는 `amfidont`).
diff --git a/docs/README_zh.md b/docs/README_zh.md
index a7b9ace3..1927ae32 100644
--- a/docs/README_zh.md
+++ b/docs/README_zh.md
@@ -71,10 +71,10 @@ csrutil allow-research-guests enable
然后重启进入 macOS,用 [`amfidont`](https://github.com/zqxwce/amfidont)(或 [`amfree`](https://github.com/retX0/amfree))将仓库加入白名单:
```bash
-sudo amfidont --path <repo>
+sudo amfidont --path <path_to_vphone-cli.app>
```
-> `less`(无补丁)变体需要方案 A,或者搭配 `amfidont -S` 的方案 B(`sudo amfidont -S --path <repo>`)。
+> `less`(无补丁)变体需要方案 A,或者搭配 `amfidont -S` 的方案 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)。
**依赖:**
@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key
把二进制加入你的 `PATH`,这样下面的示例就能原样运行:
```bash
-cd .build/release
+cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -109,7 +109,7 @@ vphone-cli --help
vphone-cli vm create myphone -V jb # -V / --variant
```
-不带源标志时,它会下载一对默认的、经过测试的 iPhone + cloudOS 固件。要选择特定固件,请传入 **`-i`/`--iphone-source`** 和 **`-c`/`--cloudos-source`**——每个都接受 **URL** 或**本地 `.ipsw` 路径**(已验证可用的固件对见[测试环境](#测试环境)):
+随后会提示你选择 iOS <-> cloudOS 配对;你也可以通过传入 **`-i`/`--iphone-source`** 和/或 **`-c`/`--cloudos-source`** 指定其中之一(或两者)。例如:
```bash
# 使用本地 IPSW
@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \
# 或使用 URL——下载后缓存到 ~/.vphone/ipsws
vphone-cli vm create myphone -V jb \
- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"
+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
+ -c "https://.../399b6..."
```
-CFW 安装阶段需要 root 权限(挂载宿主机磁盘),并会提示输入 `sudo`;传入 `-s <pw>`(`--sudo-password`)可无人值守运行。加上 `-v` 可观看恢复过程(pmd3 日志,带颜色),`-vv` 显示 pmd3 调试细节,`-vvv` 显示 vphone-cli 的内部跟踪。然后启动它:
+然后启动它:
```bash
vphone-cli vm launch myphone
```
-虚拟机存放在位于 `~/.vphone/VMs/` 的**库**中(任何命令都可用 `--library-root <dir>` 覆盖)。运行任何虚拟机命令时不带名称(例如 `vphone-cli vm launch`),即可从你的虚拟机菜单中选择。
-
## 命令
`vphone-cli vm create` 会运行整个流水线;下面的各个步骤让你可以手动驱动它,或重新运行某一个阶段。
@@ -181,6 +179,18 @@ vphone-cli vm launch myphone # 6. 首次启动
有几个步骤(DFU 恢复、IPSW 处理)通过 Python 运行。首次使用时,vphone-cli 会基于宿主机上较新的 `python3`(3.11+)并使用捆绑的 `requirements.txt`,在 `~/.vphone/venv` 处配置一个自包含的 venv——因此签名后的 `.app` 是**可移植的**:把它复制到任何地方(例如 `/Applications`),无需仓库即可运行。配置是自动进行的;运行 `vphone-cli setup` 可提前完成配置。用 `VPHONE_PYTHON=/path/to/python3` 指定特定的解释器,或用 `VPHONE_VENV_DIR=/path` 迁移 venv。
+## 位置
+
+vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库和 `.app` 之外,以便签名后的包保持可移植:
+
+| 路径 | 内容 |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `~/.vphone/VMs/` | 虚拟机包——每个虚拟机一个目录。这是库;可用 `$VPHONE_LIBRARY_ROOT` 覆盖。 |
+| `~/.vphone/ipsws/`| 已下载的 iPhone + cloudOS IPSW,缓存后在多个虚拟机间复用。 |
+| `~/.vphone/tools/`| `fw prepare` 期间获取的 APFS seal-volume 制品(`apfs_sealvolume_<version>`)缓存。 |
+| `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 |
+| `~/.vphone/venv/` | 自动配置的 Python 环境(见 [Python 运行时](#python-运行时);可用 `$VPHONE_VENV_DIR` 覆盖)。 |
+
## 常见问题
**`zsh: killed ./vphone-cli`** —— AMFI/debug 限制未被绕过;见[前置条件](#前置条件)(`amfi_get_out_of_my_way=1` 或 `amfidont`)。
diff --git a/sources/VPhoneCore/VPhoneFirmwareCatalog.swift b/sources/VPhoneCore/VPhoneFirmwareCatalog.swift
new file mode 100644
index 00000000..26e7ec7a
--- /dev/null
+++ b/sources/VPhoneCore/VPhoneFirmwareCatalog.swift
@@ -0,0 +1,70 @@
+import Foundation
+
+// MARK: - VPhoneFirmwarePairing
+
+/// A known iPhone-IPSW ↔ cloudOS pairing for iPhone17,3, with friendly names for
+/// prompts and the direct download URLs `fw prepare` consumes.
+public struct VPhoneFirmwarePairing: Sendable, Equatable {
+ public let iosName: String
+ public let iosURL: String
+ public let cloudosName: String
+ public let cloudosURL: String
+
+ public init(iosName: String, iosURL: String, cloudosName: String, cloudosURL: String) {
+ self.iosName = iosName
+ self.iosURL = iosURL
+ self.cloudosName = cloudosName
+ self.cloudosURL = cloudosURL
+ }
+}
+
+// MARK: - VPhoneCloudOSOption
+
+public struct VPhoneCloudOSOption: Sendable, Equatable {
+ public let name: String
+ public let url: String
+ public init(name: String, url: String) { self.name = name; self.url = url }
+}
+
+// MARK: - VPhoneFirmwareCatalog
+
+/// The known downloadable iPhone/cloudOS pairings. Prompts show the friendly
+/// `iosName`/`cloudosName`; selection resolves to the URLs.
+public enum VPhoneFirmwareCatalog {
+ // cloudOS images (one per major); referenced by multiple iPhone builds.
+ static let cloud261 = "https://updates.cdn-apple.com/private-cloud-compute/399b664dd623358c3de118ffc114e42dcd51c9309e751d43bc949b98f4e31349"
+ static let cloud262 = "https://updates.cdn-apple.com/private-cloud-compute/0cb00f22e0f7a8b33995b49b2bdca77f781ed6093a09c570ac21b0f012bab908"
+ static let cloud263 = "https://updates.cdn-apple.com/private-cloud-compute/edc92b58ab7e2f207a6407fd0a0e1a60f7d43bf9d93325bf6d3db3e154ee5525"
+ static let cloud264 = "https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64"
+
+ public static let pairings: [VPhoneFirmwarePairing] = [
+ .init(iosName: "iOS 18.6.2", iosURL: "https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),
+ .init(iosName: "iOS 26.0", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),
+ .init(iosName: "iOS 26.0.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-46329/C1717B2A-9E58-4131-A398-75D9B1D01A89/iPhone17,3_26.0.1_23A355_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),
+ .init(iosName: "iOS 26.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),
+ .init(iosName: "iOS 26.2", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-90760/1214478F-8ED8-4AE0-B693-2F63CE0259A9/iPhone17,3_26.2_23C55_Restore.ipsw", cloudosName: "cloudOS 26.2", cloudosURL: cloud262),
+ .init(iosName: "iOS 26.2.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/047-34150/D14FB1F1-B8C5-4A20-9250-8DD35EF19BF5/iPhone17,3_26.2.1_23C71_Restore.ipsw", cloudosName: "cloudOS 26.2", cloudosURL: cloud262),
+ .init(iosName: "iOS 26.3", iosURL: "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw", cloudosName: "cloudOS 26.3", cloudosURL: cloud263),
+ .init(iosName: "iOS 26.3.1", iosURL: "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw", cloudosName: "cloudOS 26.3", cloudosURL: cloud263),
+ .init(iosName: "iOS 26.4", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 26.4.1", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 26.4.2", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-60828/A4082066-CCC4-4903-89E6-FF4801EA609C/iPhone17,3_26.4.2_23E261_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 26.5", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-63074/5E6B4A05-BDBC-45FE-9606-22B8F4315989/iPhone17,3_26.5_23F77_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 26.5.2", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/140-25549/1AFB1F72-E48E-476A-9C21-42B27C846C01/iPhone17,3_26.5.2_23F84_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 26.6", iosURL: "https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-58193/1F477C3E-934B-43C0-B428-753B9E005EC0/iPhone17,3_26.6_23G71_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 27 beta 1", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/122-99394/32118457-A80B-4953-BF2A-11F74FD7D375/iPhone17,3_27.0_24A5355q_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 27 beta 2", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-21207/F0510574-F649-48C5-B535-0A477E342BFB/iPhone17,3_27.0_24A5370h_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 27 beta 3", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-35950/D135F5B5-C2BE-4630-8AE9-C78A6F0E8381/iPhone17,3_27.0_24A5380h_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ .init(iosName: "iOS 27 beta 4", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-57108/5E816D0E-89BB-4B95-8825-6A3EDF22E509/iPhone17,3_27.0_24A5390f_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),
+ ]
+
+ /// Distinct cloudOS images (first-seen order) for the "choose the cloudOS" prompt.
+ public static var cloudOSOptions: [VPhoneCloudOSOption] {
+ var seen = Set<String>()
+ var out: [VPhoneCloudOSOption] = []
+ for p in pairings where seen.insert(p.cloudosName).inserted {
+ out.append(VPhoneCloudOSOption(name: p.cloudosName, url: p.cloudosURL))
+ }
+ return out
+ }
+}
diff --git a/sources/VPhoneCore/VPhoneFirmwarePicker.swift b/sources/VPhoneCore/VPhoneFirmwarePicker.swift
new file mode 100644
index 00000000..607977ff
--- /dev/null
+++ b/sources/VPhoneCore/VPhoneFirmwarePicker.swift
@@ -0,0 +1,132 @@
+import Foundation
+
+// MARK: - VPhoneFirmwarePickerError
+
+public enum VPhoneFirmwarePickerError: Error, CustomStringConvertible, Equatable {
+ case aborted
+ case invalidSelection
+
+ public var description: String {
+ switch self {
+ case .aborted: "firmware selection aborted"
+ case .invalidSelection: "no valid firmware selection made"
+ }
+ }
+}
+
+// MARK: - VPhoneFirmwareSources
+
+/// The resolved `fw prepare` sources — a URL or local path per component, or
+/// nil to let `fw_prepare.sh` fall back to its built-in default.
+public struct VPhoneFirmwareSources: Sendable, Equatable {
+ public let iphoneSource: String?
+ public let cloudosSource: String?
+ public init(iphoneSource: String?, cloudosSource: String?) {
+ self.iphoneSource = iphoneSource
+ self.cloudosSource = cloudosSource
+ }
+}
+
+// MARK: - VPhoneFirmwarePicker
+
+public enum VPhoneFirmwarePicker {
+ /// Resolve the iPhone/cloudOS sources for `vm create`, prompting only for
+ /// what's missing. Both given → passthrough. Non-interactive → passthrough
+ /// (fw_prepare defaults fill any gap). Neither given → pick a full pairing.
+ /// One given → prompt for just the other. Prompts show friendly names; the
+ /// result carries URLs. I/O is injected so the logic is unit-testable.
+ public static func resolve(
+ iphone: String?,
+ cloudos: String?,
+ isInteractive: Bool,
+ maxRetries: Int = 5,
+ read: () -> String?,
+ write: (String) -> Void
+ ) throws -> VPhoneFirmwareSources {
+ let iphone = (iphone?.isEmpty == true) ? nil : iphone
+ let cloudos = (cloudos?.isEmpty == true) ? nil : cloudos
+
+ // Nothing to prompt for: both supplied, or we can't prompt anyway.
+ if (iphone != nil && cloudos != nil) || !isInteractive {
+ return VPhoneFirmwareSources(iphoneSource: iphone, cloudosSource: cloudos)
+ }
+
+ if iphone == nil, cloudos == nil {
+ let p = try pickPairing(maxRetries: maxRetries, read: read, write: write)
+ return VPhoneFirmwareSources(iphoneSource: p.iosURL, cloudosSource: p.cloudosURL)
+ }
+ if iphone == nil { // cloudOS supplied, choose the iPhone build
+ let p = try pickIPhone(maxRetries: maxRetries, read: read, write: write)
+ return VPhoneFirmwareSources(iphoneSource: p.iosURL, cloudosSource: cloudos)
+ }
+ // iPhone supplied, choose the cloudOS image
+ let c = try pickCloudOS(maxRetries: maxRetries, read: read, write: write)
+ return VPhoneFirmwareSources(iphoneSource: iphone, cloudosSource: c.url)
+ }
+
+ // MARK: - Prompts
+
+ static func pickPairing(
+ maxRetries: Int, read: () -> String?, write: (String) -> Void
+ ) throws -> VPhoneFirmwarePairing {
+ let pairings = VPhoneFirmwareCatalog.pairings
+ let w = pairings.map(\.iosName.count).max() ?? 0
+ let idx = try choose(
+ "Select a firmware pairing to download:",
+ pairings.map { $0.iosName.padding(toLength: w, withPad: " ", startingAt: 0)
+ + " (→ \($0.cloudosName))" },
+ maxRetries: maxRetries, read: read, write: write)
+ let p = pairings[idx]
+ write("→ \(p.iosName) + \(p.cloudosName)")
+ return p
+ }
+
+ static func pickIPhone(
+ maxRetries: Int, read: () -> String?, write: (String) -> Void
+ ) throws -> VPhoneFirmwarePairing {
+ let pairings = VPhoneFirmwareCatalog.pairings
+ let idx = try choose(
+ "Select an iPhone firmware to download:",
+ pairings.map(\.iosName),
+ maxRetries: maxRetries, read: read, write: write)
+ let p = pairings[idx]
+ write("→ \(p.iosName)")
+ return p
+ }
+
+ static func pickCloudOS(
+ maxRetries: Int, read: () -> String?, write: (String) -> Void
+ ) throws -> VPhoneCloudOSOption {
+ let options = VPhoneFirmwareCatalog.cloudOSOptions
+ let idx = try choose(
+ "Select a cloudOS firmware to download:",
+ options.map(\.name),
+ maxRetries: maxRetries, read: read, write: write)
+ let c = options[idx]
+ write("→ \(c.name)")
+ return c
+ }
+
+ /// Show a numbered menu and read a 1-based index (mirrors VPhoneVMPicker).
+ static func choose(
+ _ prompt: String, _ labels: [String],
+ maxRetries: Int, read: () -> String?, write: (String) -> Void
+ ) throws -> Int {
+ write(prompt)
+ let iw = String(labels.count).count // right-align indices so labels start in one column
+ for (i, label) in labels.enumerated() {
+ let n = String(i + 1)
+ let padded = String(repeating: " ", count: iw - n.count) + n
+ write(" [\(padded)] \(label)")
+ }
+ for _ in 0..<maxRetries {
+ write("Enter number: ")
+ guard let line = read() else { throw VPhoneFirmwarePickerError.aborted }
+ let choice = line.trimmingCharacters(in: .whitespacesAndNewlines)
+ if choice.isEmpty { continue }
+ if let n = Int(choice), n >= 1, n <= labels.count { return n - 1 }
+ write(" '\(choice)' is not a valid selection.")
+ }
+ throw VPhoneFirmwarePickerError.invalidSelection
+ }
+}
diff --git a/sources/vphone-cli/VPhoneFirmwareSelection.swift b/sources/vphone-cli/VPhoneFirmwareSelection.swift
new file mode 100644
index 00000000..cdb98ffe
--- /dev/null
+++ b/sources/vphone-cli/VPhoneFirmwareSelection.swift
@@ -0,0 +1,18 @@
+import Foundation
+import VPhoneCore
+
+enum VPhoneFirmwareSelection {
+ private static var isTTY: Bool { isatty(FileHandle.standardInput.fileDescriptor) != 0 }
+ private static func err(_ s: String) { FileHandle.standardError.write(Data((s + "\n").utf8)) }
+
+ /// Resolve `vm create`'s iPhone/cloudOS sources, prompting on a TTY for
+ /// whichever component the user didn't pass. Non-interactive or fully
+ /// specified → returns the inputs unchanged (fw_prepare defaults fill gaps).
+ static func resolve(iphone: String?, cloudos: String?) throws -> VPhoneFirmwareSources {
+ try VPhoneFirmwarePicker.resolve(
+ iphone: iphone, cloudos: cloudos,
+ isInteractive: isTTY,
+ read: { readLine(strippingNewline: true) },
+ write: { err($0) })
+ }
+}
diff --git a/sources/vphone-cli/VPhoneVMCreateCLI.swift b/sources/vphone-cli/VPhoneVMCreateCLI.swift
index 5500e85d..6c60ccf4 100644
--- a/sources/vphone-cli/VPhoneVMCreateCLI.swift
+++ b/sources/vphone-cli/VPhoneVMCreateCLI.swift
@@ -29,10 +29,13 @@ struct VPhoneVMCreateCommand: ParsableCommand {
func run() throws {
let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()
let selfExe = VPhoneResources.runningExecutable()
+ // Prompt for any firmware component not supplied on the command line.
+ let sources = try VPhoneFirmwareSelection.resolve(iphone: iphoneSource, cloudos: cloudosSource)
let orchestrator = VPhoneCreateOrchestrator(
library: lib.library, resources: resources, selfExecutable: selfExe)
try orchestrator.run(.init(
- name: name, variant: variant, iphoneSource: iphoneSource, cloudosSource: cloudosSource,
+ name: name, variant: variant,
+ iphoneSource: sources.iphoneSource, cloudosSource: sources.cloudosSource,
sudoPassword: sudoPassword, spoofBuild: spoofBuild, forceDSCMaxSlide: forceDSCMaxSlide,
interactive: interactive, verbosity: VPhoneVerbosity(count: verboseCount)))
}
diff --git a/tests/VPhoneCoreTests/FirmwarePickerTests.swift b/tests/VPhoneCoreTests/FirmwarePickerTests.swift
new file mode 100644
index 00000000..f3f5f7a3
--- /dev/null
+++ b/tests/VPhoneCoreTests/FirmwarePickerTests.swift
@@ -0,0 +1,143 @@
+@testable import VPhoneCore
+import Testing
+
+struct FirmwarePickerTests {
+ /// A scripted stdin: pops one line per `read()` call.
+ private func reader(_ lines: [String?]) -> () -> String? {
+ var i = 0
+ return { defer { i += 1 }; return i < lines.count ? lines[i] : nil }
+ }
+
+ // MARK: - Catalog integrity
+
+ @Test func catalogHasEighteenPairings() {
+ #expect(VPhoneFirmwareCatalog.pairings.count == 18)
+ }
+
+ @Test func everyPairingIsPopulated() {
+ for p in VPhoneFirmwareCatalog.pairings {
+ #expect(!p.iosName.isEmpty)
+ #expect(p.iosURL.hasPrefix("https://"))
+ #expect(p.iosURL.hasSuffix(".ipsw"))
+ #expect(p.cloudosName.hasPrefix("cloudOS "))
+ #expect(p.cloudosURL.contains("/private-cloud-compute/"))
+ }
+ }
+
+ @Test func cloudOSOptionsAreDistinctInFirstSeenOrder() {
+ let opts = VPhoneFirmwareCatalog.cloudOSOptions
+ #expect(opts.map(\.name) == ["cloudOS 26.1", "cloudOS 26.2", "cloudOS 26.3", "cloudOS 26.4"])
+ #expect(Set(opts.map(\.url)).count == opts.count) // no dup URLs
+ }
+
+ // MARK: - Passthrough
+
+ @Test func bothProvidedPassesThrough() throws {
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: "a.ipsw", cloudos: "b.dmg", isInteractive: true,
+ read: { nil }, write: { _ in })
+ #expect(out == VPhoneFirmwareSources(iphoneSource: "a.ipsw", cloudosSource: "b.dmg"))
+ }
+
+ @Test func nonInteractivePassesThroughEvenWhenIncomplete() throws {
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: false,
+ read: { nil }, write: { _ in })
+ #expect(out == VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil))
+ }
+
+ @Test func emptyStringsTreatedAsUnset() throws {
+ // Non-interactive + empty → passthrough as nil (no prompt), not "".
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: "", cloudos: "", isInteractive: false,
+ read: { nil }, write: { _ in })
+ #expect(out == VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil))
+ }
+
+ // MARK: - Prompt: neither provided
+
+ @Test func neitherProvidedPicksFullPairing() throws {
+ // "1" → first pairing (iOS 18.6.2 → cloudOS 26.1).
+ let first = VPhoneFirmwareCatalog.pairings[0]
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ read: reader(["1"]), write: { _ in })
+ #expect(out == VPhoneFirmwareSources(iphoneSource: first.iosURL, cloudosSource: first.cloudosURL))
+ }
+
+ @Test func neitherProvidedResolvesBothFromChosenPairing() throws {
+ let idx = 8 // iOS 26.4 (menu number 9), paired with cloudOS 26.4
+ let p = VPhoneFirmwareCatalog.pairings[idx]
+ #expect(p.iosName == "iOS 26.4")
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ read: reader([String(idx + 1)]), write: { _ in })
+ #expect(out.iphoneSource == p.iosURL)
+ #expect(out.cloudosSource == p.cloudosURL)
+ }
+
+ // MARK: - Prompt: only one side missing
+
+ @Test func iPhoneProvidedPromptsForCloudOSOnly() throws {
+ // cloudOS menu: [1]26.1 [2]26.2 [3]26.3 [4]26.4 → pick 4.
+ let opts = VPhoneFirmwareCatalog.cloudOSOptions
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: "custom.ipsw", cloudos: nil, isInteractive: true,
+ read: reader(["4"]), write: { _ in })
+ #expect(out.iphoneSource == "custom.ipsw") // untouched
+ #expect(out.cloudosSource == opts[3].url) // chosen cloudOS 26.4
+ }
+
+ @Test func cloudOSProvidedPromptsForIPhoneOnly() throws {
+ let p = VPhoneFirmwareCatalog.pairings[3] // iOS 26.1 (menu 4)
+ #expect(p.iosName == "iOS 26.1")
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: "custom.dmg", isInteractive: true,
+ read: reader(["4"]), write: { _ in })
+ #expect(out.iphoneSource == p.iosURL) // chosen iPhone build
+ #expect(out.cloudosSource == "custom.dmg") // untouched
+ }
+
+ // MARK: - Menu formatting
+
+ @Test func pairingMenuIsColumnAligned() throws {
+ var lines: [String] = []
+ _ = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ read: reader(["1"]), write: { lines.append($0) })
+ let menu = lines.filter { $0.hasPrefix(" [") }
+ #expect(menu.count == 18)
+ // Label text starts in one column regardless of 1- vs 2-digit index.
+ let labelStarts = Set(menu.map { $0.range(of: "] ")!.upperBound.utf16Offset(in: $0) })
+ #expect(labelStarts.count == 1)
+ // The "(→ cloudOS …)" arrow lands in one column across every row.
+ let arrowCols = Set(menu.map { $0.range(of: "(→")!.lowerBound.utf16Offset(in: $0) })
+ #expect(arrowCols.count == 1)
+ }
+
+ // MARK: - Retry / abort semantics
+
+ @Test func retriesThenSucceeds() throws {
+ let first = VPhoneFirmwareCatalog.pairings[0]
+ let out = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ read: reader(["", "999", "garbage", "1"]), write: { _ in })
+ #expect(out.iphoneSource == first.iosURL)
+ }
+
+ @Test func eofAborts() {
+ #expect(throws: VPhoneFirmwarePickerError.aborted) {
+ _ = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ read: { nil }, write: { _ in })
+ }
+ }
+
+ @Test func tooManyInvalidThrows() {
+ #expect(throws: VPhoneFirmwarePickerError.invalidSelection) {
+ _ = try VPhoneFirmwarePicker.resolve(
+ iphone: nil, cloudos: nil, isInteractive: true,
+ maxRetries: 2, read: reader(["x", "y", "z"]), write: { _ in })
+ }
+ }
+}