Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Document cloudOS releases without vphone600 components

Maximilian Paßcb4c18a10c2d
diff --git a/Documents/Guides/compatibility.md b/Documents/Guides/compatibility.md
index f93434f7..04a76823 100644
--- a/Documents/Guides/compatibility.md
+++ b/Documents/Guides/compatibility.md
@@ -15,19 +15,24 @@ These are the two iPhone17,3 combinations exercised with the native JB pipeline
| --- | --- | --- | --- |
| PR #486 | `17,3_26.6.2_23G90` | `26.4-23E5207q` | JB patches, restore, CFW, boot, vphoned ping |
| PR #486 | `17,3_27.0_24A435` | `26.4-23E5207q` | JB patches, restore, CFW, boot, vphoned ping |
+| Research board | `17,3_26.6_23G71` | `26.6-23G71` | standard and Minimal presets from the CLI, standard from Launchpad (2026-10-20): converted device tree and SEP, kernelcache mix, restore, CFW, boot, vphoned ping |
+| Research board | `17,3_26.5_23F77` | `26.5-23F75` | standard preset from the CLI (2026-10-20): GPU driver from a temporary cloudOS restore, kernelcache mix, restore, CFW, boot, vphoned ping |
+| Research board | `17,3_26.4_23E246` | `26.4-23E244` | standard preset from the CLI (2026-10-20): GPU driver from a temporary cloudOS restore, kernelcache mix, restore, CFW, boot, vphoned ping |
-The cloudOS 26.4 beta image (`26.4-23E5207q`) is the newest one that contains `vphone600ap`, the identity the guest's kernel, SEP and device tree come from. Every cloudOS release after it was checked on 2026-10-03 and lists only the PCC boards and `vresearch101ap`: `iPhone99,11` is gone from `SupportedProductTypes`, and there is no `kernelcache.*.vphone600`, `sep-firmware.vphone600` or `DeviceTree.vphone600ap`. None of them can boot a guest; `fw prepare` refuses them before extracting anything.
-
-| cloudOS | `vresearch101ap` | `vphone600ap` |
-| --- | --- | --- |
-| `26.4-23E5207q` (beta) | yes | yes |
-| `26.4-23E244` | yes | no |
-| `26.4.1-23E254` | yes | no |
-| `26.5-23F75` | yes | no |
-| `26.5.2-23F83` | yes | no |
-| `26.6-23G71` | yes | no |
-| `26.6.1-23G82` | yes | no |
-| `26.7-23H20` | yes | no |
+The cloudOS 26.4 beta image (`26.4-23E5207q`) is the newest one that contains `vphone600ap`, the identity the guest's kernel, SEP and device tree come from, and it stays the recommended cloudOS: it needs nothing beyond vphone-cli. Every cloudOS release after it was checked on 2026-10-03 and lists only the PCC boards and `vresearch101ap`: `iPhone99,11` is gone from `SupportedProductTypes`, and there is no `kernelcache.*.vphone600`, `sep-firmware.vphone600` or `DeviceTree.vphone600ap`.
+
+On such a cloudOS the research board stands in (the Research Board patch set): `fw patch` turns its device tree and SEP into vphone600's and rebuilds its kernelcache with the vphone600 virtualisation kexts, from a recipe for that kernelcache. That needs an `ipsw` with `kernel extract --kdk` and root for the link (`vphone-cli fw kernelcache`; see [the recipes](../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)). `fw prepare` refuses a cloudOS no recipe covers. `fw catalog` lists each iOS release's own cloudOS beside the recommended one, and Launchpad offers it under Firmware.
+
+| cloudOS | `vresearch101ap` | `vphone600ap` | kernelcache recipe |
+| --- | --- | --- | --- |
+| `26.4-23E5207q` (beta) | yes | yes | not needed |
+| `26.4-23E244` | yes | no | yes |
+| `26.4.1-23E254` | yes | no | no |
+| `26.5-23F75` | yes | no | yes |
+| `26.5.2-23F83` | yes | no | no |
+| `26.6-23G71` | yes | no | yes |
+| `26.6.1-23G82` | yes | no | no |
+| `26.7-23H20` | yes | no | yes |
Use `vphone-cli fw catalog` to inspect the current catalogue. Other iPhone and iPad versions may work with `26.4-23E5207q`, but they have not passed this same end-to-end check.
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index d9d4046f..dc7f4ca6 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -1,3 +1,4 @@
+| `~/.vphone/kernelcache/` | Kernelcache mixes for cloudOS releases without vphone600 components, their staged volumes and the donor extraction |
# Create and run a VM
[Documentation](../README.md) · [Host setup](host-setup.md) · [Compatibility](compatibility.md)
@@ -23,6 +24,8 @@ By default that pipeline builds a [template](#templates) rather than the VM itse
`fw prepare` creates a temporary vphone VM with no network device, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. The extracted bundle is cached per cloudOS build in `~/.vphone/gpu-drivers/`, so later machines on the same cloudOS skip the temporary restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.
+A cloudOS after the 26.4 beta has no vphone600 components, and the research board stands in ([Compatibility](compatibility.md)). Its kernelcache is rebuilt with the vphone600 virtualisation kexts, which needs an `ipsw` with `kernel extract --kdk` and root for the link. Run the whole creation as `sudo VPHONE_IPSW=/path/to/ipsw vphone-cli vm create ...`, or stage the mix as yourself after `fw prepare` with `VPHONE_IPSW=/path/to/ipsw vphone-cli fw kernelcache <vm>`, link it with `sudo vphone-cli fw kernelcache <vm>`, and continue with `fw patch` as usual.
+
The build also ships an arm64e GPU compiler plugin in the bundle. `fw prepare` copies it into the staged GPU bundle before firmware patching and installation.
Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.
@@ -134,6 +137,8 @@ It works out the key as `vm create` does. The builds come from the IPSWs when th
Launchpad 2.9 creates machines from templates by default. New Machine opens on a short page: the name, the device and iOS version from the firmware catalog, and a Slim System switch. A row below it sums up the rest and opens Advanced Options, four pages for hardware; the template and its parts (the trim tier and kept languages, the service profile, and which system apps go); the Core Bundle, custom IPSWs and patches; and the location, network and restore options. The row counts the settings that differ from the defaults and names anything there that stops Create. Turning off Create from a template restores the machine on its own, as `--no-template` does, with keys of its own and without slimming. Apple Account is not offered: the guest refuses its sign-in either way, so Launchpad passes `--accounts-off` whenever the service profile is trimmed. The sheet grows with its page up to 600 points and scrolls past that, so its buttons stay on a laptop screen.
+Under Firmware, a release that also runs on its own cloudOS (`fw catalog`'s third column) offers that cloudOS beside the recommended one, with the `ipsw` that stages the kernelcache mix. The creation then stages the mix as you and has the helper link it as root, which asks for authorization once.
+
The creation runs `vm template find` first. When a current template matches, it clones the machine (`vm create --template <id> --skip-first-boot`) and boots it. When none does, it builds the template in a temporary machine of the same library, named `template-` and eight hex digits, with its usual steps (restore, then `cfw install` through the helper), then `vm template trim`, the headless `vm template setup --strict` and `vm template adopt --iphone-source … --cloudos-source … --expect <id>`, and clones the machine from the result. The setup boot fails when an app it should remove stays, and the adopt fails when the build's key comes out other than the one `find` computed, so a build is never saved under an id later creations would not find. Each is a step of its own with its duration, and a failed one shows the reason `vphone-cli` gave.
Per-patch overrides from New Machine's Patch Settings are split the way the template key splits them. Boot-chain overrides are part of the key: the template is built with them, and `find` looks for one with them. Guest patch overrides are not: the template is built without them, and after the clone the creation records them on the new machine with `fw set-patches` and writes them with `cfw update-environment` through the helper (the Apply guest patches step) before its first boot. A template therefore never hands one creation's guest patch choice to another. Once it has built a template, the creation offers to delete the two IPSWs it came from; nothing is deleted without confirming.
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index b6ab72e0..c749ee82 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -3460,6 +3460,9 @@ cloudOS without vphone600ap and refuses one whose kernelcache no recipe covers.
board's.
Checked on 2026-10-19: a `minimal` VM of iOS 26.6 on cloudOS 26.6 (23G71) restores
-and boots, and vphoned answers. The 26.4 (23E244), 26.5 and 26.7 recipes are the
-ones the research workflow built and validated statically (26.4 also booted
-there); they have not run through this pipeline yet.
+and boots, and vphoned answers. Checked on 2026-10-20 with the standard preset:
+iOS 26.5 (23F77) on cloudOS 26.5 (23F75) and iOS 26.4 (23E246) on cloudOS 26.4
+(23E244) restore and boot the same way, their GPU driver taken from a temporary
+cloudOS restore. The 26.7 recipe is one the research workflow built and
+validated statically; it has not run through this pipeline yet (26.7 has no
+iPhone release to pair it with).
diff --git a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
index 3f0af13e..2e35e512 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
@@ -294,9 +294,13 @@ struct FirmwareMatrixParsingTests {
readme: RealData.repositoryCompatibilityGuide(),
device: Fixture.d,
)
- #expect(tested.count == 2)
+ #expect(tested.count == 5)
#expect(tested.contains(VPhoneFirmwareBuildID(version: "26.6.2", build: "23G90")))
#expect(tested.contains(VPhoneFirmwareBuildID(version: "27.0", build: "24A435")))
+ // The research board rows: each release on its own cloudOS.
+ for (version, build) in [("26.4", "23E246"), ("26.5", "23F77"), ("26.6", "23G71")] {
+ #expect(tested.contains(VPhoneFirmwareBuildID(version: version, build: build)))
+ }
#expect(tested.allSatisfy { !$0.version.isEmpty && !$0.build.isEmpty })
#expect(tested.allSatisfy { !$0.version.contains("`") && !$0.build.contains("`") })
}