Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Split the user guides into one page per subject

Lakr233c50f96001663
diff --git a/Documents/Guides/core-bundles.md b/Documents/Guides/core-bundles.md
new file mode 100644
index 00000000..aa04ad05
--- /dev/null
+++ b/Documents/Guides/core-bundles.md
@@ -0,0 +1,80 @@
+# Core Bundles and local builds
+
+[Documentation](../README.md) · [Launchpad command line](launchpad-cli.md) · [Bundle integration](bundle-integration.md)
+
+## One bundle per machine
+
+Every machine is bound to one installed `VPhone.bundle` version, chosen when
+it is created and kept in `launchpad.json` in the machine folder. Installing a
+bundle never changes a machine's binding. A machine is made of three layers,
+each from a bundle at a different time:
+
+| Layer | What | Comes from |
+| --- | --- | --- |
+| Host Programs | `vphone-cli`, `vphone-vm` | The bound bundle, on every command. A new binding applies at the next start. |
+| Guest Environment | vphoned and the hook dylibs | `cfw install` at creation, and `cfw update-environment` (stopped machine) later. |
+| Boot Chain | Patched firmware, restore, CFW patches | `fw patch`, `restore` and `cfw install` at creation. After that, `vphone-cli fw set-patches` changes the choice and `vphone-cli fw patches <vm>` lists what has not reached the guest: guest patches apply at the next `cfw update-environment`, AVPBooter at the next `fw patch`, a kernel patch with `cfw update-kernel` (data-preserving, no restore tree needed), and the rest of the boot chain (TXM, DeviceTree, LLB) only with a restore, which erases the guest. Launchpad shows the count in the inspector. |
+
+The **default** bundle (formerly "active") decides only the version
+`vm create` binds when `--bundle` is not given, and what `exec` and
+library-wide commands run with. A new install becomes the default unless
+`--keep-default` is passed. The first start of a machine in a Launchpad
+session checks its bundle (execution policy exception, AMFI, host preflight)
+once.
+
+Local builds install as `<version>-local.<hash>`, the hash taken from the
+bundle's code-signature seal, so two builds of one version sit side by side.
+Older stores may still hold `<version>-local` or `<version>-ci.<commit>`.
+
+## Testing a VPhone.bundle build
+
+For the one-time kernel and guest update that enables persistent shader caches
+on an existing VM, see [Persistent shader caches](shader-cache.md).
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+
+# Installs as <version>-local.<hash>, makes it the default, adds the execution
+# policy exception, allows the new vphone-vm cdhash and runs host preflight.
+vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+
+# Move an existing machine to it; --update-environment also redeploys the
+# new vphoned and hook dylibs (the machine must be stopped).
+vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
+
+vphone-launchpad-cli vm start research-01 --wait
+vphone-launchpad-cli guest rpc research-01 device.info
+vphone-launchpad-cli guest rpc research-01 apps.list '{}'
+vphone-launchpad-cli vm log research-01 --lines 100
+vphone-launchpad-cli vm stop research-01
+```
+
+The exact version is in the install result and in `bundle list`. The first
+step that needs the helper after its five-minute authorization expires asks
+for an administrator password on the Mac, as the window does.
+
+## Comparing two builds
+
+Install both without moving the default, then give each its own machine:
+
+```sh
+vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle list # note both versions
+
+vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
+vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
+```
+
+Machines created this way differ in all three layers. To compare only host
+programs and guest environment on one boot chain, clone a machine in the
+window and rebind the copy:
+
+```sh
+vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
+```
+
+`vm list` shows which bundle each layer came from. `bundle remove` refuses a
+version while a machine is bound to it; rebind or delete those machines first.
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index 75f41381..7974843f 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -2,7 +2,7 @@
[Documentation](../README.md) · [Host setup](host-setup.md) · [Compatibility](compatibility.md)
-The public firmware workflow has one mode. A patch preset selects which patches apply (see [Templates](#templates) for how presets enter the template key), and `--block` or `--allow` adjusts single patches. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.
+The public firmware workflow has one mode. A patch preset selects which patches apply (see [Templates](templates.md) for how presets enter the template key), and `--block` or `--allow` adjusts single patches. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.
## One-command flow
@@ -17,49 +17,15 @@ vphone-cli vm create myphone \
Creation runs prepare → firmware patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. The caller must provide root privileges for CFW installation; this bundle has no authorization dialog or privilege helper. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.
-By default that pipeline builds a [template](#templates) rather than the VM itself, and the VM is cloned from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from the same template instead of restoring again. Pass `--no-template` to build the VM on its own, as before.
+By default that pipeline builds a [template](templates.md) rather than the VM itself, and the VM is cloned from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from the same template instead of restoring again. Pass `--no-template` to build the VM on its own, as before.
`--iphone-version` or `--iphone-build` instead of `--iphone-source` resolves the IPSW as `fw prepare` does, for `--device` (iPhone17,3 by default). Without `--cloudos-source` the cloudOS is the one the catalog recommends for that release, as `fw catalog` lists it.
`--cpu`, `--memory`, `--network` and `--unlock-at-startup` set those `vm config` settings on the new VM (defaults: 8 cores, 8192 MB, nat, off). `--skip-first-boot` leaves out the final boot, for a caller that boots the VM itself.
-## Many machines
+Before patching, creation prepares the firmware: a temporary cloudOS restore supplies the GPU driver, and a cloudOS without vphone600 components needs a rebuilt kernelcache. See [Firmware preparation](firmware-preparation.md). To create several machines from one list, see [Create many machines](many-machines.md).
-`vm create-bulk <list.plist>` creates every machine a plist describes. Each key is a `vm create` option's long name, with its value: a string or integer, `true` for a flag, an array for `keep-apps`. `defaults` apply to every machine, a machine's own keys win, and `false` clears a default. Relative paths resolve against the plist's folder. `library-root` puts the machines in another library; `-l` on the command line overrides it.
-
-```xml
-<dict>
- <key>version</key> <integer>1</integer>
- <key>defaults</key>
- <dict>
- <key>library-root</key> <string>~/vphone-lab</string>
- <key>iphone-version</key> <string>26.1</string>
- <key>preset</key> <string>presets/lab.plist</string>
- <key>cpu</key> <integer>4</integer>
- </dict>
- <key>machines</key>
- <array>
- <dict><key>name</key> <string>ci-1</string></dict>
- <dict><key>name</key> <string>ci-2</string></dict>
- <dict>
- <key>name</key> <string>fuzz</string>
- <key>iphone-build</key> <string>23F77</string>
- <key>iphone-version</key> <false/>
- <key>no-template</key> <true/>
- </dict>
- </array>
-</dict>
-```
-
-Every machine must name its firmware (`iphone-version`, `iphone-build`, or `iphone-source` with `cloudos-source`) or a `template`, so nothing prompts. All machines are checked as `vm create` checks them before the first is made, and `--dry-run` prints each one's `vm create` command. A name that exists is an error. `--skip-existing` skips it, so a run that stopped can be run again for the rest; a machine that failed is left as it stopped, so delete it first or it is skipped too. `--force-override` deletes that VM just before its machine is created, and refuses one that is running or a folder that is not a VM. Machines are created in order, so those with one template key clone the template the first one built, and the first failure stops the run. Run it with `sudo` when a machine needs a build, as `vm create`.
-
-`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 virtualization kexts. KDK extraction runs natively; only the kmutil link needs root. After `fw prepare`, stage the mix as yourself with `vphone-cli fw kernelcache <vm>`, link it with `sudo vphone-cli fw kernelcache <vm> --link-only`, and continue with `fw patch` as usual. The old `--ipsw` argument is still accepted but ignored.
-
-A kernel only boots in the layout Apple linked it with, and kmutil takes the layout from the Mac it runs on: macOS 26.4 and later link the iOS 26.4+ kernelcaches (kernel-last), macOS 15 and 26.0–26.3 the older ones (kernel-first). When this Mac has the other layout, another Mac or a macOS VM links the mix over ssh: set `VPHONE_KMUTIL_SSH=<user>@<host>` (and `VPHONE_KMUTIL_SSH_PASSWORD=<password>` without ssh keys and passwordless sudo there) for `fw kernelcache` or the creation. The staged volume is uploaded to that Mac's `/private/var/tmp`, linked there as root and removed; nothing on this Mac needs root for it. Remote Login must be on, and the user must be allowed to use sudo.
-
-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.
+## Start and stop
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.
@@ -72,139 +38,6 @@ Closing the VM window, ⌘Q, `vm stop` and Control-C in the `vm launch` terminal
`vm launch` starts the guest without waiting for vphoned; the daemon connects during boot. The VM window and menu provide Home/power keys, app installation and file browsing. The host control socket is `<VM bundle>/vphone.sock`: one JSON line in, one out. Connections are served concurrently, and the socket also exists with `--no-graphics`, where `tap` and `swipe` go through vphoned's touch injection and screen images come from the guest. Besides `tap`, `swipe`, `key` and `screenshot`, `{"t":"rpc","method":"<vphoned method>","params":{…}}` calls any method in `Research/vphoned_http_api.md`. For example, `input.key` with `{"name":"cmd+v"}` pastes and `input.type` types text. No SSH or VNC endpoint is installed by this workflow.
-## Device name
-
-The guest shows the VM's name as its device name, in Xcode's device list and `xcrun devicectl list devices`, and cannot be renamed from inside the guest or from Finder, Xcode or `idevicename`: a rename there reports success and changes nothing. `vphone-vm` hands the name to the guest each time it connects to vphoned, a few seconds into every boot, and the guest keeps it for the next boot. After `vm rename`, Finder and `ideviceinfo` see the new name as soon as the machine is up; Xcode and `devicectl` read it when the device appears and may show the old name until the following boot. An existing machine moved to a bundle with this feature receives the guest library with its environment update and uses it from the boot after that. The guest's own name stays in its preferences, untouched. A VM name of more than 255 UTF-8 bytes, or with a control character, is not used, and the guest shows its own name. See `Research/Guest/device_name_pinning.md`.
-
-## Clock and time zone
-
-The guest follows the Mac's time zone and clock. `vphone-vm` sends the Mac's zone each time it connects to vphoned, and the Mac's time then and every minute after, so a guest that was off for a day, or sat under a sleeping Mac, is back on the Mac's time within a minute without reaching an NTP server. A guest within a second of the Mac is left alone. To give the guest another date or time, pick it in the guest's Settings › General › Date & Time: that turns its automatic time off and the Mac's time is no longer applied. Turning Set Automatically on there brings the Mac's time back.
-
-## Templates
-
-A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to (every patch it resolves to, guest ones included, for a preset the bundle does not ship: a preset file or one in `~/.vphone/patches_presets` can change under the same identifier, and a clone keeps its template's guest patches), the bundle series (`2.9` for 2.9.x), the disk size, what is trimmed from the guest's System volume (`--trim`), and the slimming switches below. Then:
-
-- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template recorded with the same two sources, as [`vm template find`](#finding-a-template) works them out; a local IPSW that has been deleted counts as not there.
-- Otherwise the IPSWs are downloaded if they are not there, and the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
-
-```sh
-vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
-vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
-vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
-```
-
-`--template <id>` clones from a template by its identifier (or a unique prefix of four or more digits) and takes no IPSW options. `--device`, `--preset`, `--disk-size` and the slimming switches, when given, must match the template's; a clone cannot change them. CPU, memory, screen and network are not part of the key.
-
-### Offline trim
-
-After `cfw install`, a template build deletes system files the guest never needs from its System volume, offline, with the volume mounted on the host. `--trim` on `vm create` (default `standard`) and `--tier` on `vm template trim` pick the tier:
-
-| Tier | Deletes | About |
-| --- | --- | --- |
-| `none` | nothing | |
-| `conservative` | the contents of `usr/standalone/update` (software-update ramdisk, baseband firmware) | 0.35 GB |
-| `standard` | conservative, plus the AirPods/Beats pairing assets (`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), the watch faces (`NanoTimeKit/FaceBundles`) and the `LinguisticData/RequiredAssets_*.bundle` of every language not kept | 1.2 GB |
-| `aggressive` | reserved: refused until it has been validated on a guest | |
-
-`--keep-languages` (default `en,zh-Hans,zh`; English is always kept) chooses the languages standard keeps. The tier, the version of the list and the kept languages are part of the template key (`standard/1/en,zh,zh-Hans`), so templates trimmed differently never match. Trimming cannot be undone: a clone cannot get the files back.
-
-The deleted files free nothing at first. The guest's original system snapshot (`orig-fs.disabled.rn-*`, left by `cfw install`) still holds every block, and the host cannot delete it, even as root. The setup boot deletes it as its first step, and only then is the space returned. So a trim is refused for a template that gets no setup boot, and a trimmed template is frozen or adopted only once its snapshot is gone. `vm template trim` needs no root, runs on a stopped machine that has not been cloned from a template, or on an unfinished `.building-…` folder, and refuses a frozen template.
-
-### Setup boot and slimming
-
-The setup boot finishes the template the way every clone should start. It boots the template once and, through vphoned, in this order:
-
-1. deletes the `orig-fs.disabled.rn-*` APFS snapshot `cfw install` left (it holds about 20 MB, and every file trimmed from the System volume until it is gone);
-2. skips Setup Assistant (`setup.skip`);
-3. waits for first-boot work to settle (`setup.settle`, up to 10 minutes): installd expands the removable system apps on the first boot;
-4. removes the system apps (`apps.remove_system`, backups kept in the guest);
-5. applies the service profile (`services.profile.apply`), which includes turning off the sign-in follow-up daemons (`followupd`, `appleidsetupd`);
-6. reboots, then checks: no snapshot left, Setup done, none of the profile's services running, the removed apps gone, vphoned answering;
-7. clears the device name `vphone-vm` pinned for this boot, and shuts the guest down cleanly.
-
-Every step has a deadline. A failed step stops the VM, records nothing and leaves the build unfrozen; `vm create` names the step and how to retry it.
-
-| Switch | Default | Effect |
-| --- | --- | --- |
-| `--slim on\|off` | on | `off` trims nothing and keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
-| `--trim none\|conservative\|standard` | standard | The offline trim above. |
-| `--keep-languages <list>` | `en,zh-Hans,zh` | The languages `--trim standard` keeps. |
-| `--service-profile trimmed\|none` | trimmed | vphoned's trimmed profile: about 140 launchd jobs off, the App Store daemons and sign-in follow-up among them. A phone with this profile cannot pair an Apple Watch (see `Research/Guest/watch_pairing.md`). |
-| `--remove-apps on\|off` | on | Removes App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My and Wallet. Camera and Phone stay. |
-| `--keep-apps <ids>` | none | Bundle IDs from that list to keep, comma-separated (`com.apple.findmy,com.apple.Passbook`). |
-| `--accounts-off` | off | Also turns off `akd`, `amsaccountsd` and `appleaccountd`. The guest then cannot sign in to an Apple Account. |
-
-Each choice is part of the key, so templates with different slimming live side by side and each serves only the creates that ask for it. Removed apps and the profile stay reversible on a clone: `apps.restore_system` puts an app back from its backup, and `services.profile.apply {"profile":"none"}` turns back on exactly what the profile turned off (both through `vphone-launchpad-cli guest rpc`, or Guest System in Launchpad).
-
-What every clone inherits from the template: Setup done, the apps and services as the setup boot left them, the first-boot work installd and the indexers did, and the Data volume as of that boot. It does not inherit a device name: the template's pin is cleared, so a clone shows `iPhone` until its own VM connects and pins the clone's name. A new identity also means the Mac asks "Trust This Computer?" again.
-
-### Finishing a VM as a template
-
-To turn a VM straight after creating it into a template, stop it, trim it, give it the setup boot, and adopt it. This is what Launchpad does for a template it has to build (below):
-
-```sh
-vphone-cli vm stop phone-src
-vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
-vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
-vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
-vphone-cli vm create phone-d --template <id> --skip-first-boot
-```
-
-`--iphone-source` and `--cloudos-source` on `vm template adopt` record the IPSWs the VM was created from in its `Template.plist`, as a `vm create` that builds a template does. `--json` prints the new template as `vm template show --json` does.
-
-`--expect <id>` on `vm template adopt` refuses, and leaves the VM where it is, unless its records give the template identifier `<id>`: the `id` that `vm template find` printed for the options the VM was built with. Without the check, a VM whose setup boot fell short (an app it could not remove) would be saved under another key, and every later `vm create` with those options would miss it and build another template. The refusal names the fields that differ when it can work out the expected key, which it can when a template or build in the library has it or when only the slimming differs; otherwise it prints the VM's own key to compare. With `--json` the refusal is also printed to stdout as `{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}`, and the command exits with status 1.
-
-`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. With `--strict` it fails instead, records nothing, and the setup boot can be run again: use it when the VM is to be adopted with `--expect` under the key `vm template find` gave for the same switches. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
-
-### Finding a template
-
-`vm template find` answers what template a `vm create` with the same options would clone from, without downloading, restoring or changing anything:
-
-```sh
-vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
-```
-
-It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves once the IPSWs were deleted, local ones included. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them. The JSON has `resolved`, `resolvedBy` (`ipsw` or `template`), `id`, `summary`, `key`, `template` (the matching template as `vm template show --json` prints it, current or stale), `usable` (it exists and is current), `building` (a create holds its build lock) and, when unresolved, `reason`.
-
-### In Launchpad
-
-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 2.12 Launchpad interface still shows its legacy ipsw selector for older compatible bundles. Native Core Bundle extraction ignores the selected tool path; the CLI no longer needs it.
-
-The iPhone XS Max runs iOS 18.1 to 18.7.2, each on its own release's cloudOS, with no template and the Minimal preset by default; Standard works as well (checked on 18.6). Its pairings always rebuild the kernelcache, so Firmware asks for the `ipsw`, and for the macOS builder: `user@host` of a Mac or macOS VM running macOS 15 or 26.0 to 26.3 with Remote Login on, and its password for ssh and sudo (empty with ssh keys and passwordless sudo). Launchpad keeps the builder like the `ipsw`, but not the password, which reaches `vphone-cli` only in its environment (`VPHONE_KMUTIL_SSH_PASSWORD`). The creation then stages and links the mix as you, over ssh; from macOS 26.4 on the builder is required, on an older Mac without one the helper links it as root.
-
-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.
-
-File > Templates… lists every library's templates with their machines, slimming, size and state, and deletes them. Guest System… (in a machine's Actions menu and inspector) switches a running machine's service profile and restores system apps the template removed. The inspector and the machine list show each machine's exclusive disk use beside what its files allocate: the blocks no other machine or template holds, which deleting it frees (a local Time Machine snapshot taken before keeps them until it expires).
-
-### Shared secrets
-
-Every machine cloned from one template shares, with the template and with each other, its SEP root secret, its Data volume keys and the data the restore and the setup boot wrote. One clone could in principle decrypt another's Data volume. A VM that needs keys of its own, for example to sign in to Apple services for multi-device research, should be created with `--no-template` (which takes no slimming switches). Clones get a new ECID, UDID and MAC address on their first start, as with `vm clone --new-identity`, and share every unchanged block with the template on APFS: a new clone costs almost nothing until it starts writing, and a slimmed template leaves it little first-boot work to write.
-
-```sh
-vphone-cli vm template list # id, key summary, STALE with the reasons
-vphone-cli vm template show <id> --json
-vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
-vphone-cli vm template setup myphone # the setup boot, on a stopped VM
-vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
-vphone-cli vm template delete <id>
-```
-
-- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
-- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
-- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
-- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks. `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
-
- ```
- note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
- ```
-- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks, though a local Time Machine snapshot taken while it existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
-
## Manual stages
Use these when investigating or repeating one phase. Keep a DFU boot running while `restore` talks to it:
@@ -226,50 +59,9 @@ vphone-cli vm launch myphone
The online restore obtains its ticket in process. For an offline restore, see `vphone-cli restore --help` for `--get-shsh` and `--offline`. The manual flow does not perform the automatic first-boot ping check from `vm create`.
-## Library, firmware and backups
-
-| Default path | Contents |
-| --- | --- |
-| `~/.vphone/machines/<name>/` | One VM, including its disk, `config.plist`, and patch work files |
-| `~/.vphone/ipsws/` | Remote source IPSWs, shared by every VM; local IPSWs are read in place |
-| `~/.vphone/gpu-drivers/<version>_<build>/` | GPU driver bundles extracted from cloudOS, shared by every VM |
-| `~/.vphone/kernelcache/` | Kernelcache mixes for cloudOS releases without vphone600 components, their staged volumes and the donor extraction |
-
-`VPHONE_ROOT` relocates the VM library and both caches. `VPHONE_LIBRARY_ROOT` takes precedence for the library alone, and `--ipsw-cache <dir>` on `vm create` and `fw prepare` for the IPSW cache alone. Downloaded IPSWs stay cached until you delete them (in Launchpad, with File > Downloaded IPSWs…), so a second VM from the same URL downloads nothing; the prepared restore tree is removed after a successful `vm create` unless `--keep-artifacts` is set. VMs prepared by an earlier build may still hold a `.ipsw-cache/` directory; it is safe to delete, and `vm export` leaves it out.
-
-A remote IPSW downloads over four connections at once when its server answers HTTP range requests, as Apple's CDN does; each connection fetches 32 MB segments in turn and resumes a dropped segment where it stopped. `--download-connections <n>` on `fw prepare` sets the count (1 to 16); 1 downloads the IPSW as a single stream, which is also what a server that ignores ranges gets.
-
-```sh
-vphone-cli vm list
-vphone-cli vm info myphone
-vphone-cli vm clone myphone copy
-vphone-cli vm clone myphone second --new-identity
-vphone-cli vm export myphone --out myphone.tzst
-vphone-cli vm import myphone.tzst --name restored
-```
-
-`vm clone` copies a stopped machine, using APFS copy-on-write when available; it refuses while the source runs. A plain copy keeps everything, including the device identity (machine identifier and MAC address), so it is a backup and cannot run beside the original.
-
-`--new-identity` makes a second device instead. The copy gets a new machine identifier (ECID), and with it a new UDID, and a new MAC address on its first start. Its fixed IPv4 address, port forwards and a hand-chosen mDNS name are cleared, since they would collide with the original's; an mDNS name `--mdns on` derived from the original's name follows the new name, as on rename. Set new ones with `vm config` if you need them. The guest keeps the original's data, apps and settings, and no restore is needed. Before lockdown tools such as `ideviceinstaller` work, unlock the copy and trust this Mac again. On APFS a copy shares its disk blocks with the original and holds only what it changes, about 0.35 GB after its first boots, although `du` and Finder report the full size for each.
-
-Do not swap `SEPStorage`, `nvram.bin` or the disk image between machines: they were made together by one restore, and a guest whose SEP storage does not match its disk panics at boot.
-
-Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM. Launchpad places CFW scratch files on the VM library's mounted external volume when applicable; standalone `vphone-cli cfw install` defaults to `/private/var/tmp` and accepts `--work-parent` for a root-owned private directory.
-
-### Sharing disk space between VMs
-
-Two VMs restored separately from the same IPSW share nothing on disk, although much of their disk images is the same: two iOS 27.0 iPhones hold about 8.6 GB of identical bytes at the same places in their roughly 20 GB of data, mostly the system volume. `vm rebase` makes a stopped VM store those blocks once with another VM's, or with a template's:
-
-```sh
-vphone-cli vm rebase second --onto first --dry-run
-vphone-cli vm rebase second --onto 3f2a91c0d4e7
-```
-
-It rebuilds `second`'s disk image from an APFS clone of the base's and writes in only the blocks that differ. `--onto` takes a VM name or a template identifier (or a unique prefix of one) from `vm template list`; a VM wins when a name matches both. Every byte is compared with the original before the image is replaced, so the guest sees exactly the same disk. Only the disk image changes: `SEPStorage`, `nvram.bin`, `config.plist` and the device identity stay as they are. Rebasing onto a template leaves the template as it is, and the VM does not become one of its clones: `vm template show` does not list it. Both must be stopped and on the same APFS volume, and the volume needs free space for the blocks that are written until the old image is released. `--dry-run` reports what would be shared and written without writing anything.
-
-The saving is the **newly shared** figure. Bytes that are identical but already the same blocks on disk are reported as **already shared**, and rebasing them frees nothing. VMs made by `vm create` from one template already share its blocks, so rebasing one onto another, or onto that template, frees little; the command says so before it compares and again when the saving is under 0.1 GB. The VMs worth rebasing are ones restored without a template (`--no-template`) or imported.
+## Further reading
-- The space comes back only when nothing else holds the old image's blocks. Snapshots of the VM, and clones made from it, keep them; delete those first or expect no saving.
-- `du` and Finder still count each image at its full size. Free space on the volume (`df`) is the honest measure.
-- The two images drift apart again as either VM writes to its disk. A base that is never booted, such as a template, stays the best base, and rebasing again later recovers what drifted.
-- A rebase that is interrupted leaves the VM unchanged and may leave a hidden `.rebase-*` folder in it; delete that folder.
+- [Templates](templates.md): how `vm create` reuses one restore for many machines, and how to slim, find and delete templates.
+- [Device name and clock](device-name-and-clock.md): what the guest takes from the VM and the Mac.
+- [Library, firmware and backups](library-and-backups.md): where machines and caches live, clones and exports.
+- [Sharing disk space between VMs](sharing-disk-space.md): `vm rebase`.
diff --git a/Documents/Guides/device-name-and-clock.md b/Documents/Guides/device-name-and-clock.md
new file mode 100644
index 00000000..230fb968
--- /dev/null
+++ b/Documents/Guides/device-name-and-clock.md
@@ -0,0 +1,11 @@
+# Device name and clock
+
+[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Networking](networking.md)
+
+## Device name
+
+The guest shows the VM's name as its device name, in Xcode's device list and `xcrun devicectl list devices`, and cannot be renamed from inside the guest or from Finder, Xcode or `idevicename`: a rename there reports success and changes nothing. `vphone-vm` hands the name to the guest each time it connects to vphoned, a few seconds into every boot, and the guest keeps it for the next boot. After `vm rename`, Finder and `ideviceinfo` see the new name as soon as the machine is up; Xcode and `devicectl` read it when the device appears and may show the old name until the following boot. An existing machine moved to a bundle with this feature receives the guest library with its environment update and uses it from the boot after that. The guest's own name stays in its preferences, untouched. A VM name of more than 255 UTF-8 bytes, or with a control character, is not used, and the guest shows its own name. See `Research/Guest/device_name_pinning.md`.
+
+## Clock and time zone
+
+The guest follows the Mac's time zone and clock. `vphone-vm` sends the Mac's zone each time it connects to vphoned, and the Mac's time then and every minute after, so a guest that was off for a day, or sat under a sleeping Mac, is back on the Mac's time within a minute without reaching an NTP server. A guest within a second of the Mac is left alone. To give the guest another date or time, pick it in the guest's Settings › General › Date & Time: that turns its automatic time off and the Mac's time is no longer applied. Turning Set Automatically on there brings the Mac's time back.
diff --git a/Documents/Guides/firmware-preparation.md b/Documents/Guides/firmware-preparation.md
new file mode 100644
index 00000000..394c4548
--- /dev/null
+++ b/Documents/Guides/firmware-preparation.md
@@ -0,0 +1,13 @@
+# Firmware preparation
+
+[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Compatibility](compatibility.md)
+
+What `vm create` and `fw prepare` do with the two IPSWs before the firmware is patched.
+
+`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 virtualization kexts. KDK extraction runs natively; only the kmutil link needs root. After `fw prepare`, stage the mix as yourself with `vphone-cli fw kernelcache <vm>`, link it with `sudo vphone-cli fw kernelcache <vm> --link-only`, and continue with `fw patch` as usual. The old `--ipsw` argument is still accepted but ignored.
+
+A kernel only boots in the layout Apple linked it with, and kmutil takes the layout from the Mac it runs on: macOS 26.4 and later link the iOS 26.4+ kernelcaches (kernel-last), macOS 15 and 26.0–26.3 the older ones (kernel-first). When this Mac has the other layout, another Mac or a macOS VM links the mix over ssh: set `VPHONE_KMUTIL_SSH=<user>@<host>` (and `VPHONE_KMUTIL_SSH_PASSWORD=<password>` without ssh keys and passwordless sudo there) for `fw kernelcache` or the creation. The staged volume is uploaded to that Mac's `/private/var/tmp`, linked there as root and removed; nothing on this Mac needs root for it. Remote Login must be on, and the user must be allowed to use sudo.
+
+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.
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.md
index 113d9891..af6d67e0 100644
--- a/Documents/Guides/launchpad-cli.md
+++ b/Documents/Guides/launchpad-cli.md
@@ -1,5 +1,7 @@
# Launchpad command line
+[Documentation](../README.md) · [Core Bundles and local builds](core-bundles.md)
+
`vphone-launchpad-cli` ships in `vphone-launchpad.app/Contents/MacOS`. It
drives the running Launchpad over a Unix socket at
`~/Library/Application Support/vphone-launchpad/control.sock` (mode 0600,
@@ -26,82 +28,7 @@ ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /us
vphone-launchpad-cli help
```
-## Core Bundle per machine
-
-Every machine is bound to one installed `VPhone.bundle` version, chosen when
-it is created and kept in `launchpad.json` in the machine folder. Installing a
-bundle never changes a machine's binding. A machine is made of three layers,
-each from a bundle at a different time:
-
-| Layer | What | Comes from |
-| --- | --- | --- |
-| Host Programs | `vphone-cli`, `vphone-vm` | The bound bundle, on every command. A new binding applies at the next start. |
-| Guest Environment | vphoned and the hook dylibs | `cfw install` at creation, and `cfw update-environment` (stopped machine) later. |
-| Boot Chain | Patched firmware, restore, CFW patches | `fw patch`, `restore` and `cfw install` at creation. After that, `vphone-cli fw set-patches` changes the choice and `vphone-cli fw patches <vm>` lists what has not reached the guest: guest patches apply at the next `cfw update-environment`, AVPBooter at the next `fw patch`, a kernel patch with `cfw update-kernel` (data-preserving, no restore tree needed), and the rest of the boot chain (TXM, DeviceTree, LLB) only with a restore, which erases the guest. Launchpad shows the count in the inspector. |
-
-The **default** bundle (formerly "active") decides only the version
-`vm create` binds when `--bundle` is not given, and what `exec` and
-library-wide commands run with. A new install becomes the default unless
-`--keep-default` is passed. The first start of a machine in a Launchpad
-session checks its bundle (execution policy exception, AMFI, host preflight)
-once.
-
-Local builds install as `<version>-local.<hash>`, the hash taken from the
-bundle's code-signature seal, so two builds of one version sit side by side.
-Older stores may still hold `<version>-local` or `<version>-ci.<commit>`.
-
-## Testing a VPhone.bundle build
-
-For the one-time kernel and guest update that enables persistent shader caches
-on an existing VM, see [Persistent shader caches](shader-cache.md).
-
-```sh
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-
-# Installs as <version>-local.<hash>, makes it the default, adds the execution
-# policy exception, allows the new vphone-vm cdhash and runs host preflight.
-vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
-
-# Move an existing machine to it; --update-environment also redeploys the
-# new vphoned and hook dylibs (the machine must be stopped).
-vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
-
-vphone-launchpad-cli vm start research-01 --wait
-vphone-launchpad-cli guest rpc research-01 device.info
-vphone-launchpad-cli guest rpc research-01 apps.list '{}'
-vphone-launchpad-cli vm log research-01 --lines 100
-vphone-launchpad-cli vm stop research-01
-```
-
-The exact version is in the install result and in `bundle list`. The first
-step that needs the helper after its five-minute authorization expires asks
-for an administrator password on the Mac, as the window does.
-
-## Comparing two builds
-
-Install both without moving the default, then give each its own machine:
-
-```sh
-vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
-vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
-vphone-launchpad-cli bundle list # note both versions
-
-vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
-vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
-```
-
-Machines created this way differ in all three layers. To compare only host
-programs and guest environment on one boot chain, clone a machine in the
-window and rebind the copy:
-
-```sh
-vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
-```
-
-`vm list` shows which bundle each layer came from. `bundle remove` refuses a
-version while a machine is bound to it; rebind or delete those machines first.
+Each machine runs through the `vphone-cli` of the bundle it is bound to. To install a local `VPhone.bundle` build, move a machine to it, or compare two builds, see [Core Bundles and local builds](core-bundles.md).
## Commands
@@ -118,7 +45,7 @@ version while a machine is bound to it; rebind or delete those machines first.
| `vm wait <name>` / `vm log <name> [--kind create\|dfu\|patch]` | Wait for vphoned; read a console log |
| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--preset` takes a preset name or the path of a preset plist (2.14), which the machine keeps a copy of. `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customized before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper (its Userspace debugging box, `userspace-debugging` under Features in `vphone-cli fw patches`, is an `--allow` for each patch it lists); the kernelcache mix of a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest) is staged with `fw kernelcache` and linked by the helper as root; `--ipsw` is optional and only passed on to a 2.12.0 bundle, which stages with it, as New Machine's ipsw field (a 2.12.1 bundle extracts natively); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used |
| `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version. `--update-environment` also redeploys that version's guest environment and needs a stopped machine; a disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`: run `cfw update-environment` to finish |
-| `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](networking.md#addresses-held-by-old-macs)) |
+| `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](network-addresses.md#addresses-held-by-old-macs)) |
| `cfw install <name>` | Install CFW into a stopped machine with its own bundle, through the helper. The helper puts temporary work files on the VM library's external volume when applicable. It and the two updates below refuse a disk another process has open, naming it (`12925 tail`). |
| `cfw update-environment <name>` | Redeploy the machine's own bundle's guest resources (vphoned, hook dylibs) into it while stopped, through the helper; nothing else changes |
| `cfw update-kernel <name>` | Re-patch the kernelcache from the machine's current selection and swap it into Preboot, keeping the data (VM off); the data-preserving way to change a kernel patch on an installed VM, no restore tree needed |
diff --git a/Documents/Guides/library-and-backups.md b/Documents/Guides/library-and-backups.md
new file mode 100644
index 00000000..c5184ef5
--- /dev/null
+++ b/Documents/Guides/library-and-backups.md
@@ -0,0 +1,31 @@
+# Library, firmware and backups
+
+[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Sharing disk space](sharing-disk-space.md) · [Snapshots](snapshots.md)
+
+| Default path | Contents |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | One VM, including its disk, `config.plist`, and patch work files |
+| `~/.vphone/ipsws/` | Remote source IPSWs, shared by every VM; local IPSWs are read in place |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | GPU driver bundles extracted from cloudOS, shared by every VM |
+| `~/.vphone/kernelcache/` | Kernelcache mixes for cloudOS releases without vphone600 components, their staged volumes and the donor extraction |
+
+`VPHONE_ROOT` relocates the VM library and both caches. `VPHONE_LIBRARY_ROOT` takes precedence for the library alone, and `--ipsw-cache <dir>` on `vm create` and `fw prepare` for the IPSW cache alone. Downloaded IPSWs stay cached until you delete them (in Launchpad, with File > Downloaded IPSWs…), so a second VM from the same URL downloads nothing; the prepared restore tree is removed after a successful `vm create` unless `--keep-artifacts` is set. VMs prepared by an earlier build may still hold a `.ipsw-cache/` directory; it is safe to delete, and `vm export` leaves it out.
+
+A remote IPSW downloads over four connections at once when its server answers HTTP range requests, as Apple's CDN does; each connection fetches 32 MB segments in turn and resumes a dropped segment where it stopped. `--download-connections <n>` on `fw prepare` sets the count (1 to 16); 1 downloads the IPSW as a single stream, which is also what a server that ignores ranges gets.
+
+```sh
+vphone-cli vm list
+vphone-cli vm info myphone
+vphone-cli vm clone myphone copy
+vphone-cli vm clone myphone second --new-identity
+vphone-cli vm export myphone --out myphone.tzst
+vphone-cli vm import myphone.tzst --name restored
+```
+
+`vm clone` copies a stopped machine, using APFS copy-on-write when available; it refuses while the source runs. A plain copy keeps everything, including the device identity (machine identifier and MAC address), so it is a backup and cannot run beside the original.
+
+`--new-identity` makes a second device instead. The copy gets a new machine identifier (ECID), and with it a new UDID, and a new MAC address on its first start. Its fixed IPv4 address, port forwards and a hand-chosen mDNS name are cleared, since they would collide with the original's; an mDNS name `--mdns on` derived from the original's name follows the new name, as on rename. Set new ones with `vm config` if you need them. The guest keeps the original's data, apps and settings, and no restore is needed. Before lockdown tools such as `ideviceinstaller` work, unlock the copy and trust this Mac again. On APFS a copy shares its disk blocks with the original and holds only what it changes, about 0.35 GB after its first boots, although `du` and Finder report the full size for each.
+
+Do not swap `SEPStorage`, `nvram.bin` or the disk image between machines: they were made together by one restore, and a guest whose SEP storage does not match its disk panics at boot.
+
+Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM. Launchpad places CFW scratch files on the VM library's mounted external volume when applicable; standalone `vphone-cli cfw install` defaults to `/private/var/tmp` and accepts `--work-parent` for a root-owned private directory.
diff --git a/Documents/Guides/many-machines.md b/Documents/Guides/many-machines.md
new file mode 100644
index 00000000..a58ec428
--- /dev/null
+++ b/Documents/Guides/many-machines.md
@@ -0,0 +1,31 @@
+# Create many machines
+
+[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Templates](templates.md)
+
+`vm create-bulk <list.plist>` creates every machine a plist describes. Each key is a `vm create` option's long name, with its value: a string or integer, `true` for a flag, an array for `keep-apps`. `defaults` apply to every machine, a machine's own keys win, and `false` clears a default. Relative paths resolve against the plist's folder. `library-root` puts the machines in another library; `-l` on the command line overrides it.
+
+```xml
+<dict>
+ <key>version</key> <integer>1</integer>
+ <key>defaults</key>
+ <dict>
+ <key>library-root</key> <string>~/vphone-lab</string>
+ <key>iphone-version</key> <string>26.1</string>
+ <key>preset</key> <string>presets/lab.plist</string>
+ <key>cpu</key> <integer>4</integer>
+ </dict>
+ <key>machines</key>
+ <array>
+ <dict><key>name</key> <string>ci-1</string></dict>
+ <dict><key>name</key> <string>ci-2</string></dict>
+ <dict>
+ <key>name</key> <string>fuzz</string>
+ <key>iphone-build</key> <string>23F77</string>
+ <key>iphone-version</key> <false/>
+ <key>no-template</key> <true/>
+ </dict>
+ </array>
+</dict>
+```
+
+Every machine must name its firmware (`iphone-version`, `iphone-build`, or `iphone-source` with `cloudos-source`) or a `template`, so nothing prompts. All machines are checked as `vm create` checks them before the first is made, and `--dry-run` prints each one's `vm create` command. A name that exists is an error. `--skip-existing` skips it, so a run that stopped can be run again for the rest; a machine that failed is left as it stopped, so delete it first or it is skipped too. `--force-override` deletes that VM just before its machine is created, and refuses one that is running or a folder that is not a VM. Machines are created in order, so those with one template key clone the template the first one built, and the first failure stops the run. Run it with `sudo` when a machine needs a build, as `vm create`.
diff --git a/Documents/Guides/network-addresses.md b/Documents/Guides/network-addresses.md
new file mode 100644
index 00000000..3174c6aa
--- /dev/null
+++ b/Documents/Guides/network-addresses.md
@@ -0,0 +1,96 @@
+# MAC and IP addresses
+
+[Documentation](../README.md) · [Networking](networking.md) · [Port forwarding](network-port-forwarding.md) · [Machines reaching each other](network-peers.md)
+
+## MAC address
+
+The first launch gives the guest's network card a random, locally administered
+MAC address and saves it in `config.plist`, the way it saves the machine
+identifier. The guest then keeps one identity, and one DHCP lease, across
+launches. To set or replace it:
+
+```sh
+vphone-cli vm config <name> --mac 02:11:22:33:44:55
+vphone-cli vm config <name> --mac random # a new one now
+vphone-cli vm config <name> --mac auto # a new one at the next launch
+```
+
+A cloned machine keeps the MAC of the original, like its machine identifier.
+Clone with `vm clone --new-identity` to give the copy new ones, or give it a
+new MAC before running both at once. `--new-identity` also clears the copy's
+fixed address, port forwards and mDNS name.
+
+## Addresses held by old MACs
+
+In `nat` mode the Mac's DHCP server keeps each address bound to the MAC it
+was given to, even after the lease runs out. It hands that address to anyone
+else only once every other address in the range is taken. Deleting a machine
+or replacing its MAC leaves its address bound to a MAC nothing uses any more,
+and so does every launch made before MACs were saved. New guests then get
+higher and higher addresses, until they reach the fixed addresses picked high
+in the range.
+
+`vm leases` lists the leases on the shared network and who owns each. It
+needs `VPhone.bundle` 2.5 or later:
+
+```sh
+vphone-cli vm leases
+sudo vphone-cli vm leases --release-orphans
+```
+
+An orphan is an iOS or iPadOS guest's lease whose MAC belongs to no machine in
+the library and whose lease has run out. `--release-orphans` removes the
+orphans from `/var/db/dhcpd_leases` and has the DHCP server read the file
+again, so it needs root. It never touches:
+
+- a machine's own lease, even one that ran out while the machine was stopped;
+- a lease that has not run out, such as a running guest's whose MAC was just
+ replaced;
+- leases of other VM apps, or of devices on Internet Sharing.
+
+Machines in another library count only when that library is named too:
+repeat `--library-root` for each. The release refuses to run when a library
+has no machines or a machine's settings cannot be read, since every lease
+there would look orphaned.
+
+In Launchpad, Host Setup shows the count under NAT Network, and Release…
+frees them after an administrator approves. It compares against every
+library Launchpad lists. From the command line:
+
+```sh
+vphone-launchpad-cli vm leases
+vphone-launchpad-cli vm leases --release
+```
+
+## Fixed address
+
+`--ip` gives the guest a fixed IPv4 address. Without a prefix, `/24` is
+assumed. `--gateway` and `--dns` are optional; `auto` returns them to the
+default, and `--ip dhcp` removes the fixed address.
+
+```sh
+vphone-cli vm config <name> --ip 192.168.64.50
+vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
+vphone-cli vm config <name> --ip dhcp
+```
+
+How the address reaches the guest depends on the mode:
+
+| Mode | Address | How it is applied |
+| --- | --- | --- |
+| `nat` | On the Mac's shared NAT network, normally `192.168.64.0/24` | vphoned writes it into the guest's network settings. The gateway and DNS are the Mac, `192.168.64.1`. |
+| `tunnel` | Any private subnet | The tunnel's own DHCP hands it out. The gateway, which is also the DNS resolver, is the subnet's first address unless `--gateway` names another. |
+| `bridged` | An address on the physical network | vphoned writes it into the guest. Set `--gateway` and `--dns` to the network's own. |
+
+In `nat` mode the address has to be on the shared network, the one every `nat`
+VM uses (vmnet's `Shared_Net_Address`, if it has been moved). For any other
+subnet, use `tunnel`. macOS 26 can give a VM a NAT network of its own, but the
+subnet then stays reserved after the VM stops (still so 40 minutes later in
+testing), and every launch on it fails meanwhile, so vphone does not use it.
+
+vphoned applies the address each time `vphone-vm` connects to it, so a guest
+changed while the Mac was not looking is put back. It only ever undoes its own
+setting: an address typed into the guest's Settings app is left alone when the
+VM goes back to DHCP. An address on the shared `nat` network is not reserved in
+the Mac's DHCP server, so pick one high in the range, such as `.200`, that DHCP
+is unlikely to have handed to another VM.
diff --git a/Documents/Guides/network-names.md b/Documents/Guides/network-names.md
new file mode 100644
index 00000000..644b2795
--- /dev/null
+++ b/Documents/Guides/network-names.md
@@ -0,0 +1,79 @@
+# Names on the network
+
+[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Tunnel mode](network-tunnel.md)
+
+## Name on the local network (mDNS)
+
+Off by default. `--mdns on` makes the guest answer to `<vm-name>.local`, with
+anything but letters and digits in the VM name turned into hyphens
+(`ipad_pro.13` becomes `ipad-pro-13.local`). `--mdns <name>` picks another
+name, and `--mdns off` puts the guest's own name back.
+
+```sh
+vphone-cli vm config <name> --mdns on
+ping <vm-name>.local
+```
+
+vphoned sets the name in the guest's network settings (`LocalHostName`) each
+time `vphone-vm` connects, and the guest's mDNSResponder announces it on every
+link it has. Besides its network card, a guest has the network link a USB-connected
+iPhone gives the Mac, which shows up on the Mac as an `en` interface with a
+`169.254` address. So the name works in
+every mode, `none` included:
+
+| Mode | `<name>.local` resolves to |
+| --- | --- |
+| `nat` | The guest's address on the shared network, and its USB link address |
+| `bridged` | The guest's LAN address, for every device on the LAN, and its USB link address on the Mac |
+| `tunnel`, `none` | The guest's USB link address, on the Mac only |
+
+The USB link address is link-local, but the Mac reaches the guest on it
+directly, so in `tunnel` mode a connection to `<name>.local` reaches a guest
+service without a port forward.
+
+If another device already uses the name, mDNS renames the guest (`name-2`).
+Renaming the VM with `vm rename` renames a name `--mdns on` derived from it;
+one picked by hand stays. A VM stopped with `vm stop` or by closing its window
+cannot withdraw its announcement, so the Mac's resolver keeps returning the
+old address until the cached record expires, which for a host address is 75
+minutes (TTL 4500 s).
+
+## This Mac's name in the guest
+
+On by default. The guest resolves this Mac's mDNS name (`scutil --get
+LocalHostName`, plus `.local`) at once, to the address it reaches the Mac at:
+
+| Mode | `<Mac>.local` in the guest |
+| --- | --- |
+| `nat` | The Mac on the shared network, usually `192.168.64.1` |
+| `tunnel` | The gateway, `192.168.127.1` by default. Connections to it reach the Mac's loopback (`127.0.0.1`), the way `10.0.2.2` does in QEMU and VirtualBox |
+| `bridged` | The Mac's address on the bridged interface |
+
+Over mDNS alone, an IPv4 lookup of the Mac's name in the guest could fail. The
+guest also hears the Mac on the network link a USB-connected iPhone gives the
+Mac, where the Mac has no IPv4 address and answers "no such record". Whichever
+link answers first decides the lookup, so an app that wants an IPv4 address
+got an error until a real answer had been cached from another link.
+
+vphoned registers the name with the guest's own mDNSResponder the way it
+holds an `/etc/hosts` line: as a local record that answers an IPv4 lookup at
+once, with that one address, without asking the network and without the
+answers it has cached. It does so each time `vphone-vm` connects, and again
+when vphoned starts, so the name is in place before apps run after a reboot.
+The guest's system volume is read-only, so `/etc/hosts` itself is not edited,
+and nothing is announced on any network. IPv6 lookups still go to mDNS.
+
+Without it, a lookup also listed the Mac's `169.254` address on the USB link,
+first. iOS routes `169.254.0.0/16` through its primary interface, so a plain
+socket connecting to that address could leave through `en0`, where nothing
+answers, and wait out its timeout.
+
+```sh
+vphone-cli vm config <name> --mac-name off # withdraw it
+```
+
+To see what the guest's resolver returns, and whether each address connects:
+
+```sh
+vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
+```
diff --git a/Documents/Guides/network-peers.md b/Documents/Guides/network-peers.md
new file mode 100644
index 00000000..ae3c9f7d
--- /dev/null
+++ b/Documents/Guides/network-peers.md
@@ -0,0 +1,26 @@
+# Machines reaching each other
+
+[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Names on the network](network-names.md)
+
+In `nat`, Virtualization.framework isolates each guest from the others on the
+Mac's shared network by default: a guest reaches the Mac and the internet, not
+another VM. vphone turns that isolation off, so `nat` machines reach each other
+directly, Bonjour included. A virtual Apple Watch pairs with a virtual iPhone
+this way. A machine that should stay apart opts out:
+
+```sh
+vphone-cli vm config <name> --nat-peers off # isolate this guest again
+vphone-cli vm config <name> --nat-peers on # the default
+```
+
+In Launchpad it is "Reach other NAT machines" in the machine's Network
+settings. It applies from the next launch.
+
+vmnet puts the machines that reach each other on a second shared network, the
+block after the first: 192.168.65.0/24 beside 192.168.64.0/24, with the Mac at
+192.168.65.1. A fixed address (`--ip`) goes on that network; a machine whose
+fixed address is on the first network keeps its isolation unless it asks for
+its peers, and then needs an address on the second one. Isolation is a setting of each
+machine's own attachment, so a machine that opts out keeps vmnet's isolation
+whatever the others do. The switch is private to Virtualization.framework; a
+version without it leaves every guest isolated and says so when the VM starts.
diff --git a/Documents/Guides/network-port-forwarding.md b/Documents/Guides/network-port-forwarding.md
new file mode 100644
index 00000000..da32113c
--- /dev/null
+++ b/Documents/Guides/network-port-forwarding.md
@@ -0,0 +1,22 @@
+# Port forwarding
+
+[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Tunnel mode](network-tunnel.md)
+
+`--forward` carries a port on the Mac into the guest, in `nat` and `tunnel`
+modes. The form is `[tcp|udp:][host-address:]host-port:guest-port`. A forward
+listens on `127.0.0.1` unless a host address is given; `0.0.0.0` makes it
+reachable from other devices on the LAN.
+
+```sh
+vphone-cli vm config <name> --forward tcp:8022:22
+vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
+vphone-cli vm config <name> --remove-forward 8022
+vphone-cli vm config <name> --clear-forwards
+```
+
+`vphone-vm` opens the listeners when the VM starts and closes them when it
+stops. In `nat` mode it connects to the guest's address: the fixed one, or the
+one vphoned reports. In `tunnel` mode the connection reaches the guest as if it
+came from the gateway. A port that is already taken on the Mac is reported in
+the VM's log and skipped; the rest still work. `bridged` puts the guest on the
+LAN with its own address, so it needs no forwards.
diff --git a/Documents/Guides/network-tunnel.md b/Documents/Guides/network-tunnel.md
new file mode 100644
index 00000000..a2daf5ed
--- /dev/null
+++ b/Documents/Guides/network-tunnel.md
@@ -0,0 +1,64 @@
+# Tunnel mode
+
+[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Port forwarding](network-port-forwarding.md)
+
+## Why it exists
+
+`nat` and `bridged` send the guest's packets out through a physical interface.
+When a VPN owns the Mac's default route (WireGuard, Cloudflare WARP, or a proxy
+app in TUN mode such as Surge or Clash), those packets skip the VPN. They leave
+unencrypted, or not at all.
+
+In `tunnel` mode the guest's network card is implemented inside `vphone-vm`.
+It answers DHCP, ARP and ping for the gateway, and turns each guest TCP
+connection and UDP flow into a normal socket on the Mac. Those sockets follow
+the Mac's routing table like any other app's, so the VPN carries them. It needs
+no root, no new network interface and no change to the Mac's network settings.
+
+In a proxy app the guest shows up as its own client, named after the machine,
+and the app's rules apply to it as they would to any other app.
+
+## What the guest sees
+
+| Item | Value |
+| --- | --- |
+| Guest address | `192.168.127.3/24` by DHCP, or the [fixed address](network-addresses.md#fixed-address) |
+| Gateway and DNS | `192.168.127.1`, or the first address of the fixed address's subnet |
+| MTU | 1500 |
+| DNS | Queries to `192.168.127.1` go to the Mac's resolver |
+| Other connections to the gateway | The Mac's loopback, `127.0.0.1` (TCP and UDP) |
+
+## Limits
+
+- **IPv4 only.** The guest gets no IPv6 address, and IPv6 traffic is dropped.
+- **Outbound only, apart from forwarded ports.** Nothing on the Mac or the LAN
+ can reach the guest through this network except the ports listed under
+ [Port forwarding](network-port-forwarding.md). USB access (`iproxy`, `ideviceinstaller`)
+ and `vphone.sock` do not use the guest network, so they still work.
+- **Ping reaches the gateway only.** ICMP to the internet is not forwarded,
+ so `ping 1.1.1.1` in the guest fails even while TCP and UDP work.
+- **Throughput is limited by `vphone-vm`.** Every packet is handled in this
+ process. Downloads and video work, but `nat` is faster when no VPN is involved.
+
+## Checking it works
+
+1. Start the machine and wait for it to finish booting.
+2. Read the guest's address:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> device.network
+ ```
+
+ `en0` should show `192.168.127.3`. If it shows only an `fe80::` address,
+ DHCP has not finished yet. Wait a few seconds and try again.
+3. Open a page in the guest:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
+ ```
+
+4. On the Mac, the connections belong to `vphone-vm` and use the VPN's address:
+
+ ```sh
+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
+ ```
diff --git a/Documents/Guides/networking.md b/Documents/Guides/networking.md
index f34b5c4d..eb59893f 100644
--- a/Documents/Guides/networking.md
+++ b/Documents/Guides/networking.md
@@ -9,7 +9,7 @@ VM starts, so a change applies from the next launch.
| --- | --- | --- |
| `nat` | Virtualization.framework's built-in NAT | The default. The Mac has no VPN, or the VPN does not need to carry the guest. |
| `bridged` | Directly on a physical interface of the Mac, with its own address on that network | The guest has to be reachable from other machines on the LAN. |
-| `tunnel` | Through ordinary connections opened by `vphone-vm` on the Mac | The Mac's traffic goes through a VPN or a proxy app, and the guest's traffic must follow it. |
+| [`tunnel`](network-tunnel.md) | Through ordinary connections opened by `vphone-vm` on the Mac | The Mac's traffic goes through a VPN or a proxy app, and the guest's traffic must follow it. |
| `none` | No network device | The guest must stay offline. |
## Choosing a mode
@@ -29,282 +29,6 @@ vphone-launchpad-cli exec vm config <name> --network tunnel
`tunnel` needs a `VPhone.bundle` that lists it in `vphone-cli vm config --help`.
An older bundle rejects the setting.
-## Why `tunnel` exists
-
-`nat` and `bridged` send the guest's packets out through a physical interface.
-When a VPN owns the Mac's default route (WireGuard, Cloudflare WARP, or a proxy
-app in TUN mode such as Surge or Clash), those packets skip the VPN. They leave
-unencrypted, or not at all.
-
-In `tunnel` mode the guest's network card is implemented inside `vphone-vm`.
-It answers DHCP, ARP and ping for the gateway, and turns each guest TCP
-connection and UDP flow into a normal socket on the Mac. Those sockets follow
-the Mac's routing table like any other app's, so the VPN carries them. It needs
-no root, no new network interface and no change to the Mac's network settings.
-
-In a proxy app the guest shows up as its own client, named after the machine,
-and the app's rules apply to it as they would to any other app.
-
-## What the guest sees
-
-| Item | Value |
-| --- | --- |
-| Guest address | `192.168.127.3/24` by DHCP, or the [fixed address](#fixed-address) |
-| Gateway and DNS | `192.168.127.1`, or the first address of the fixed address's subnet |
-| MTU | 1500 |
-| DNS | Queries to `192.168.127.1` go to the Mac's resolver |
-| Other connections to the gateway | The Mac's loopback, `127.0.0.1` (TCP and UDP) |
-
-## Limits
-
-- **IPv4 only.** The guest gets no IPv6 address, and IPv6 traffic is dropped.
-- **Outbound only, apart from forwarded ports.** Nothing on the Mac or the LAN
- can reach the guest through this network except the ports listed under
- [Port forwarding](#port-forwarding). USB access (`iproxy`, `ideviceinstaller`)
- and `vphone.sock` do not use the guest network, so they still work.
-- **Ping reaches the gateway only.** ICMP to the internet is not forwarded,
- so `ping 1.1.1.1` in the guest fails even while TCP and UDP work.
-- **Throughput is limited by `vphone-vm`.** Every packet is handled in this
- process. Downloads and video work, but `nat` is faster when no VPN is involved.
-
-## Checking it works
-
-1. Start the machine and wait for it to finish booting.
-2. Read the guest's address:
-
- ```sh
- vphone-launchpad-cli guest rpc <name> device.network
- ```
-
- `en0` should show `192.168.127.3`. If it shows only an `fe80::` address,
- DHCP has not finished yet. Wait a few seconds and try again.
-3. Open a page in the guest:
-
- ```sh
- vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
- ```
-
-4. On the Mac, the connections belong to `vphone-vm` and use the VPN's address:
-
- ```sh
- lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
- ```
-
-## MAC address
-
-The first launch gives the guest's network card a random, locally administered
-MAC address and saves it in `config.plist`, the way it saves the machine
-identifier. The guest then keeps one identity, and one DHCP lease, across
-launches. To set or replace it:
-
-```sh
-vphone-cli vm config <name> --mac 02:11:22:33:44:55
-vphone-cli vm config <name> --mac random # a new one now
-vphone-cli vm config <name> --mac auto # a new one at the next launch
-```
-
-A cloned machine keeps the MAC of the original, like its machine identifier.
-Clone with `vm clone --new-identity` to give the copy new ones, or give it a
-new MAC before running both at once. `--new-identity` also clears the copy's
-fixed address, port forwards and mDNS name.
-
-## Addresses held by old MACs
-
-In `nat` mode the Mac's DHCP server keeps each address bound to the MAC it
-was given to, even after the lease runs out. It hands that address to anyone
-else only once every other address in the range is taken. Deleting a machine
-or replacing its MAC leaves its address bound to a MAC nothing uses any more,
-and so does every launch made before MACs were saved. New guests then get
-higher and higher addresses, until they reach the fixed addresses picked high
-in the range.
-
-`vm leases` lists the leases on the shared network and who owns each. It
-needs `VPhone.bundle` 2.5 or later:
-
-```sh
-vphone-cli vm leases
-sudo vphone-cli vm leases --release-orphans
-```
-
-An orphan is an iOS or iPadOS guest's lease whose MAC belongs to no machine in
-the library and whose lease has run out. `--release-orphans` removes the
-orphans from `/var/db/dhcpd_leases` and has the DHCP server read the file
-again, so it needs root. It never touches:
-
-- a machine's own lease, even one that ran out while the machine was stopped;
-- a lease that has not run out, such as a running guest's whose MAC was just
- replaced;
-- leases of other VM apps, or of devices on Internet Sharing.
-
-Machines in another library count only when that library is named too:
-repeat `--library-root` for each. The release refuses to run when a library
-has no machines or a machine's settings cannot be read, since every lease
-there would look orphaned.
-
-In Launchpad, Host Setup shows the count under NAT Network, and Release…
-frees them after an administrator approves. It compares against every
-library Launchpad lists. From the command line:
-
-```sh
-vphone-launchpad-cli vm leases
-vphone-launchpad-cli vm leases --release
-```
-
-## Fixed address
-
-`--ip` gives the guest a fixed IPv4 address. Without a prefix, `/24` is
-assumed. `--gateway` and `--dns` are optional; `auto` returns them to the
-default, and `--ip dhcp` removes the fixed address.
-
-```sh
-vphone-cli vm config <name> --ip 192.168.64.50
-vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
-vphone-cli vm config <name> --ip dhcp
-```
-
-How the address reaches the guest depends on the mode:
-
-| Mode | Address | How it is applied |
-| --- | --- | --- |
-| `nat` | On the Mac's shared NAT network, normally `192.168.64.0/24` | vphoned writes it into the guest's network settings. The gateway and DNS are the Mac, `192.168.64.1`. |
-| `tunnel` | Any private subnet | The tunnel's own DHCP hands it out. The gateway, which is also the DNS resolver, is the subnet's first address unless `--gateway` names another. |
-| `bridged` | An address on the physical network | vphoned writes it into the guest. Set `--gateway` and `--dns` to the network's own. |
-
-In `nat` mode the address has to be on the shared network, the one every `nat`
-VM uses (vmnet's `Shared_Net_Address`, if it has been moved). For any other
-subnet, use `tunnel`. macOS 26 can give a VM a NAT network of its own, but the
-subnet then stays reserved after the VM stops (still so 40 minutes later in
-testing), and every launch on it fails meanwhile, so vphone does not use it.
-
-vphoned applies the address each time `vphone-vm` connects to it, so a guest
-changed while the Mac was not looking is put back. It only ever undoes its own
-setting: an address typed into the guest's Settings app is left alone when the
-VM goes back to DHCP. An address on the shared `nat` network is not reserved in
-the Mac's DHCP server, so pick one high in the range, such as `.200`, that DHCP
-is unlikely to have handed to another VM.
-
-## Port forwarding
-
-`--forward` carries a port on the Mac into the guest, in `nat` and `tunnel`
-modes. The form is `[tcp|udp:][host-address:]host-port:guest-port`. A forward
-listens on `127.0.0.1` unless a host address is given; `0.0.0.0` makes it
-reachable from other devices on the LAN.
-
-```sh
-vphone-cli vm config <name> --forward tcp:8022:22
-vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
-vphone-cli vm config <name> --remove-forward 8022
-vphone-cli vm config <name> --clear-forwards
-```
-
-`vphone-vm` opens the listeners when the VM starts and closes them when it
-stops. In `nat` mode it connects to the guest's address: the fixed one, or the
-one vphoned reports. In `tunnel` mode the connection reaches the guest as if it
-came from the gateway. A port that is already taken on the Mac is reported in
-the VM's log and skipped; the rest still work. `bridged` puts the guest on the
-LAN with its own address, so it needs no forwards.
-
-## Name on the local network (mDNS)
-
-Off by default. `--mdns on` makes the guest answer to `<vm-name>.local`, with
-anything but letters and digits in the VM name turned into hyphens
-(`ipad_pro.13` becomes `ipad-pro-13.local`). `--mdns <name>` picks another
-name, and `--mdns off` puts the guest's own name back.
-
-```sh
-vphone-cli vm config <name> --mdns on
-ping <vm-name>.local
-```
-
-vphoned sets the name in the guest's network settings (`LocalHostName`) each
-time `vphone-vm` connects, and the guest's mDNSResponder announces it on every
-link it has. Besides its network card, a guest has the network link a USB-connected
-iPhone gives the Mac, which shows up on the Mac as an `en` interface with a
-`169.254` address. So the name works in
-every mode, `none` included:
-
-| Mode | `<name>.local` resolves to |
-| --- | --- |
-| `nat` | The guest's address on the shared network, and its USB link address |
-| `bridged` | The guest's LAN address, for every device on the LAN, and its USB link address on the Mac |
-| `tunnel`, `none` | The guest's USB link address, on the Mac only |
-
-The USB link address is link-local, but the Mac reaches the guest on it
-directly, so in `tunnel` mode a connection to `<name>.local` reaches a guest
-service without a port forward.
-
-If another device already uses the name, mDNS renames the guest (`name-2`).
-Renaming the VM with `vm rename` renames a name `--mdns on` derived from it;
-one picked by hand stays. A VM stopped with `vm stop` or by closing its window
-cannot withdraw its announcement, so the Mac's resolver keeps returning the
-old address until the cached record expires, which for a host address is 75
-minutes (TTL 4500 s).
-
-## This Mac's name in the guest
-
-On by default. The guest resolves this Mac's mDNS name (`scutil --get
-LocalHostName`, plus `.local`) at once, to the address it reaches the Mac at:
-
-| Mode | `<Mac>.local` in the guest |
-| --- | --- |
-| `nat` | The Mac on the shared network, usually `192.168.64.1` |
-| `tunnel` | The gateway, `192.168.127.1` by default. Connections to it reach the Mac's loopback (`127.0.0.1`), the way `10.0.2.2` does in QEMU and VirtualBox |
-| `bridged` | The Mac's address on the bridged interface |
-
-Over mDNS alone, an IPv4 lookup of the Mac's name in the guest could fail. The
-guest also hears the Mac on the network link a USB-connected iPhone gives the
-Mac, where the Mac has no IPv4 address and answers "no such record". Whichever
-link answers first decides the lookup, so an app that wants an IPv4 address
-got an error until a real answer had been cached from another link.
-
-vphoned registers the name with the guest's own mDNSResponder the way it
-holds an `/etc/hosts` line: as a local record that answers an IPv4 lookup at
-once, with that one address, without asking the network and without the
-answers it has cached. It does so each time `vphone-vm` connects, and again
-when vphoned starts, so the name is in place before apps run after a reboot.
-The guest's system volume is read-only, so `/etc/hosts` itself is not edited,
-and nothing is announced on any network. IPv6 lookups still go to mDNS.
-
-Without it, a lookup also listed the Mac's `169.254` address on the USB link,
-first. iOS routes `169.254.0.0/16` through its primary interface, so a plain
-socket connecting to that address could leave through `en0`, where nothing
-answers, and wait out its timeout.
-
-```sh
-vphone-cli vm config <name> --mac-name off # withdraw it
-```
-
-To see what the guest's resolver returns, and whether each address connects:
-
-```sh
-vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
-```
-
-## Machines reaching each other
-
-In `nat`, Virtualization.framework isolates each guest from the others on the
-Mac's shared network by default: a guest reaches the Mac and the internet, not
-another VM. vphone turns that isolation off, so `nat` machines reach each other
-directly, Bonjour included. A virtual Apple Watch pairs with a virtual iPhone
-this way. A machine that should stay apart opts out:
-
-```sh
-vphone-cli vm config <name> --nat-peers off # isolate this guest again
-vphone-cli vm config <name> --nat-peers on # the default
-```
-
-In Launchpad it is "Reach other NAT machines" in the machine's Network
-settings. It applies from the next launch.
-
-vmnet puts the machines that reach each other on a second shared network, the
-block after the first: 192.168.65.0/24 beside 192.168.64.0/24, with the Mac at
-192.168.65.1. A fixed address (`--ip`) goes on that network; a machine whose
-fixed address is on the first network keeps its isolation unless it asks for
-its peers, and then needs an address on the second one. Isolation is a setting of each
-machine's own attachment, so a machine that opts out keeps vmnet's isolation
-whatever the others do. The switch is private to Virtualization.framework; a
-version without it leaves every guest isolated and says so when the VM starts.
-
## Unplugging a running VM
`vm network` acts on a VM that is running, and nothing it does is saved:
@@ -325,3 +49,11 @@ restart.
In Launchpad, Settings… has Address and Port Forwarding sections when one
machine is selected.
+
+## Further reading
+
+- [Tunnel mode](network-tunnel.md): why it exists, what the guest sees, its limits, and how to check it works.
+- [MAC and IP addresses](network-addresses.md): the saved MAC address, leases held by old MACs, and fixed addresses.
+- [Port forwarding](network-port-forwarding.md): carry a port on the Mac into the guest.
+- [Names on the network](network-names.md): the guest's `.local` name, and this Mac's name in the guest.
+- [Machines reaching each other](network-peers.md): `nat` machines on one shared network.
diff --git a/Documents/Guides/sharing-disk-space.md b/Documents/Guides/sharing-disk-space.md
new file mode 100644
index 00000000..f01828c3
--- /dev/null
+++ b/Documents/Guides/sharing-disk-space.md
@@ -0,0 +1,19 @@
+# Sharing disk space between VMs
+
+[Documentation](../README.md) · [Library and backups](library-and-backups.md) · [Templates](templates.md)
+
+Two VMs restored separately from the same IPSW share nothing on disk, although much of their disk images is the same: two iOS 27.0 iPhones hold about 8.6 GB of identical bytes at the same places in their roughly 20 GB of data, mostly the system volume. `vm rebase` makes a stopped VM store those blocks once with another VM's, or with a template's:
+
+```sh
+vphone-cli vm rebase second --onto first --dry-run
+vphone-cli vm rebase second --onto 3f2a91c0d4e7
+```
+
+It rebuilds `second`'s disk image from an APFS clone of the base's and writes in only the blocks that differ. `--onto` takes a VM name or a template identifier (or a unique prefix of one) from `vm template list`; a VM wins when a name matches both. Every byte is compared with the original before the image is replaced, so the guest sees exactly the same disk. Only the disk image changes: `SEPStorage`, `nvram.bin`, `config.plist` and the device identity stay as they are. Rebasing onto a template leaves the template as it is, and the VM does not become one of its clones: `vm template show` does not list it. Both must be stopped and on the same APFS volume, and the volume needs free space for the blocks that are written until the old image is released. `--dry-run` reports what would be shared and written without writing anything.
+
+The saving is the **newly shared** figure. Bytes that are identical but already the same blocks on disk are reported as **already shared**, and rebasing them frees nothing. VMs made by `vm create` from one template already share its blocks, so rebasing one onto another, or onto that template, frees little; the command says so before it compares and again when the saving is under 0.1 GB. The VMs worth rebasing are ones restored without a template (`--no-template`) or imported.
+
+- The space comes back only when nothing else holds the old image's blocks. Snapshots of the VM, and clones made from it, keep them; delete those first or expect no saving.
+- `du` and Finder still count each image at its full size. Free space on the volume (`df`) is the honest measure.
+- The two images drift apart again as either VM writes to its disk. A base that is never booted, such as a template, stays the best base, and rebasing again later recovers what drifted.
+- A rebase that is interrupted leaves the VM unchanged and may leave a hidden `.rebase-*` folder in it; delete that folder.
diff --git a/Documents/Guides/snapshots.md b/Documents/Guides/snapshots.md
index 3b83cc21..05bc69a3 100644
--- a/Documents/Guides/snapshots.md
+++ b/Documents/Guides/snapshots.md
@@ -74,7 +74,7 @@ what it really uses. Free space on the volume is the honest measure.
A snapshot keeps the disk blocks it was taken with. `vm rebase`, which makes a
VM share identical blocks with another VM's, frees nothing while a snapshot of
that VM still holds the old ones; see
-[Sharing disk space between VMs](create-and-run.md#sharing-disk-space-between-vms).
+[Sharing disk space between VMs](sharing-disk-space.md).
The VM must be on an APFS volume. Elsewhere `create` refuses rather than copying
a disk image that can be tens of gigabytes.
diff --git a/Documents/Guides/template-building.md b/Documents/Guides/template-building.md
new file mode 100644
index 00000000..a0bd92d1
--- /dev/null
+++ b/Documents/Guides/template-building.md
@@ -0,0 +1,47 @@
+# Building and finding templates
+
+[Documentation](../README.md) · [Templates](templates.md) · [Create and Run](create-and-run.md)
+
+## Finishing a VM as a template
+
+To turn a VM straight after creating it into a template, stop it, trim it, give it the setup boot, and adopt it. This is what Launchpad does for a template it has to build (below):
+
+```sh
+vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
+vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
+vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
+vphone-cli vm create phone-d --template <id> --skip-first-boot
+```
+
+`--iphone-source` and `--cloudos-source` on `vm template adopt` record the IPSWs the VM was created from in its `Template.plist`, as a `vm create` that builds a template does. `--json` prints the new template as `vm template show --json` does.
+
+`--expect <id>` on `vm template adopt` refuses, and leaves the VM where it is, unless its records give the template identifier `<id>`: the `id` that `vm template find` printed for the options the VM was built with. Without the check, a VM whose setup boot fell short (an app it could not remove) would be saved under another key, and every later `vm create` with those options would miss it and build another template. The refusal names the fields that differ when it can work out the expected key, which it can when a template or build in the library has it or when only the slimming differs; otherwise it prints the VM's own key to compare. With `--json` the refusal is also printed to stdout as `{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}`, and the command exits with status 1.
+
+`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. With `--strict` it fails instead, records nothing, and the setup boot can be run again: use it when the VM is to be adopted with `--expect` under the key `vm template find` gave for the same switches. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
+
+## Finding a template
+
+`vm template find` answers what template a `vm create` with the same options would clone from, without downloading, restoring or changing anything:
+
+```sh
+vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
+```
+
+It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves once the IPSWs were deleted, local ones included. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them. The JSON has `resolved`, `resolvedBy` (`ipsw` or `template`), `id`, `summary`, `key`, `template` (the matching template as `vm template show --json` prints it, current or stale), `usable` (it exists and is current), `building` (a create holds its build lock) and, when unresolved, `reason`.
+
+## In Launchpad
+
+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 2.12 Launchpad interface still shows its legacy ipsw selector for older compatible bundles. Native Core Bundle extraction ignores the selected tool path; the CLI no longer needs it.
+
+The iPhone XS Max runs iOS 18.1 to 18.7.2, each on its own release's cloudOS, with no template and the Minimal preset by default; Standard works as well (checked on 18.6). Its pairings always rebuild the kernelcache, so Firmware asks for the `ipsw`, and for the macOS builder: `user@host` of a Mac or macOS VM running macOS 15 or 26.0 to 26.3 with Remote Login on, and its password for ssh and sudo (empty with ssh keys and passwordless sudo). Launchpad keeps the builder like the `ipsw`, but not the password, which reaches `vphone-cli` only in its environment (`VPHONE_KMUTIL_SSH_PASSWORD`). The creation then stages and links the mix as you, over ssh; from macOS 26.4 on the builder is required, on an older Mac without one the helper links it as root.
+
+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.
+
+File > Templates… lists every library's templates with their machines, slimming, size and state, and deletes them. Guest System… (in a machine's Actions menu and inspector) switches a running machine's service profile and restores system apps the template removed. The inspector and the machine list show each machine's exclusive disk use beside what its files allocate: the blocks no other machine or template holds, which deleting it frees (a local Time Machine snapshot taken before keeps them until it expires).
diff --git a/Documents/Guides/templates.md b/Documents/Guides/templates.md
new file mode 100644
index 00000000..881d25f1
--- /dev/null
+++ b/Documents/Guides/templates.md
@@ -0,0 +1,84 @@
+# Templates
+
+[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Building and finding templates](template-building.md) · [Library and backups](library-and-backups.md)
+
+A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to (every patch it resolves to, guest ones included, for a preset the bundle does not ship: a preset file or one in `~/.vphone/patches_presets` can change under the same identifier, and a clone keeps its template's guest patches), the bundle series (`2.9` for 2.9.x), the disk size, what is trimmed from the guest's System volume (`--trim`), and the slimming switches below. Then:
+
+- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template recorded with the same two sources, as [`vm template find`](template-building.md#finding-a-template) works them out; a local IPSW that has been deleted counts as not there.
+- Otherwise the IPSWs are downloaded if they are not there, and the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
+
+```sh
+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
+```
+
+`--template <id>` clones from a template by its identifier (or a unique prefix of four or more digits) and takes no IPSW options. `--device`, `--preset`, `--disk-size` and the slimming switches, when given, must match the template's; a clone cannot change them. CPU, memory, screen and network are not part of the key.
+
+## Offline trim
+
+After `cfw install`, a template build deletes system files the guest never needs from its System volume, offline, with the volume mounted on the host. `--trim` on `vm create` (default `standard`) and `--tier` on `vm template trim` pick the tier:
+
+| Tier | Deletes | About |
+| --- | --- | --- |
+| `none` | nothing | |
+| `conservative` | the contents of `usr/standalone/update` (software-update ramdisk, baseband firmware) | 0.35 GB |
+| `standard` | conservative, plus the AirPods/Beats pairing assets (`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), the watch faces (`NanoTimeKit/FaceBundles`) and the `LinguisticData/RequiredAssets_*.bundle` of every language not kept | 1.2 GB |
+| `aggressive` | reserved: refused until it has been validated on a guest | |
+
+`--keep-languages` (default `en,zh-Hans,zh`; English is always kept) chooses the languages standard keeps. The tier, the version of the list and the kept languages are part of the template key (`standard/1/en,zh,zh-Hans`), so templates trimmed differently never match. Trimming cannot be undone: a clone cannot get the files back.
+
+The deleted files free nothing at first. The guest's original system snapshot (`orig-fs.disabled.rn-*`, left by `cfw install`) still holds every block, and the host cannot delete it, even as root. The setup boot deletes it as its first step, and only then is the space returned. So a trim is refused for a template that gets no setup boot, and a trimmed template is frozen or adopted only once its snapshot is gone. `vm template trim` needs no root, runs on a stopped machine that has not been cloned from a template, or on an unfinished `.building-…` folder, and refuses a frozen template.
+
+## Setup boot and slimming
+
+The setup boot finishes the template the way every clone should start. It boots the template once and, through vphoned, in this order:
+
+1. deletes the `orig-fs.disabled.rn-*` APFS snapshot `cfw install` left (it holds about 20 MB, and every file trimmed from the System volume until it is gone);
+2. skips Setup Assistant (`setup.skip`);
+3. waits for first-boot work to settle (`setup.settle`, up to 10 minutes): installd expands the removable system apps on the first boot;
+4. removes the system apps (`apps.remove_system`, backups kept in the guest);
+5. applies the service profile (`services.profile.apply`), which includes turning off the sign-in follow-up daemons (`followupd`, `appleidsetupd`);
+6. reboots, then checks: no snapshot left, Setup done, none of the profile's services running, the removed apps gone, vphoned answering;
+7. clears the device name `vphone-vm` pinned for this boot, and shuts the guest down cleanly.
+
+Every step has a deadline. A failed step stops the VM, records nothing and leaves the build unfrozen; `vm create` names the step and how to retry it.
+
+| Switch | Default | Effect |
+| --- | --- | --- |
+| `--slim on\|off` | on | `off` trims nothing and keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
+| `--trim none\|conservative\|standard` | standard | The offline trim above. |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | The languages `--trim standard` keeps. |
+| `--service-profile trimmed\|none` | trimmed | vphoned's trimmed profile: about 140 launchd jobs off, the App Store daemons and sign-in follow-up among them. A phone with this profile cannot pair an Apple Watch (see `Research/Guest/watch_pairing.md`). |
+| `--remove-apps on\|off` | on | Removes App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My and Wallet. Camera and Phone stay. |
+| `--keep-apps <ids>` | none | Bundle IDs from that list to keep, comma-separated (`com.apple.findmy,com.apple.Passbook`). |
+| `--accounts-off` | off | Also turns off `akd`, `amsaccountsd` and `appleaccountd`. The guest then cannot sign in to an Apple Account. |
+
+Each choice is part of the key, so templates with different slimming live side by side and each serves only the creates that ask for it. Removed apps and the profile stay reversible on a clone: `apps.restore_system` puts an app back from its backup, and `services.profile.apply {"profile":"none"}` turns back on exactly what the profile turned off (both through `vphone-launchpad-cli guest rpc`, or Guest System in Launchpad).
+
+What every clone inherits from the template: Setup done, the apps and services as the setup boot left them, the first-boot work installd and the indexers did, and the Data volume as of that boot. It does not inherit a device name: the template's pin is cleared, so a clone shows `iPhone` until its own VM connects and pins the clone's name. A new identity also means the Mac asks "Trust This Computer?" again.
+
+To turn a VM into a template by hand, ask which template a `vm create` would use, or see how Launchpad builds them, read [Building and finding templates](template-building.md).
+
+## Shared secrets
+
+Every machine cloned from one template shares, with the template and with each other, its SEP root secret, its Data volume keys and the data the restore and the setup boot wrote. One clone could in principle decrypt another's Data volume. A VM that needs keys of its own, for example to sign in to Apple services for multi-device research, should be created with `--no-template` (which takes no slimming switches). Clones get a new ECID, UDID and MAC address on their first start, as with `vm clone --new-identity`, and share every unchanged block with the template on APFS: a new clone costs almost nothing until it starts writing, and a slimmed template leaves it little first-boot work to write.
+
+```sh
+vphone-cli vm template list # id, key summary, STALE with the reasons
+vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
+vphone-cli vm template setup myphone # the setup boot, on a stopped VM
+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
+vphone-cli vm template delete <id>
+```
+
+- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
+- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
+- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
+- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks. `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
+
+ ```
+ note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+ ```
+- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks, though a local Time Machine snapshot taken while it existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
diff --git a/Documents/README.md b/Documents/README.md
index 380aa348..982da9ad 100644
--- a/Documents/README.md
+++ b/Documents/README.md
@@ -2,19 +2,61 @@
Start with the [Launchpad quick start](../README.md#get-started). For terminal use, see [Create and Run](Guides/create-and-run.md). There is one public firmware mode; a patch preset (Standard, Minimal and others) selects the patches, and `--block` or `--allow` adjusts single patches.
-| Guide | Use it for |
+## Get Started
+
+| Page | Use it for |
| --- | --- |
| [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 |
-| [Snapshots](Guides/snapshots.md) | Saving a stopped VM's disk state and reverting to it |
+| [Create and Run](Guides/create-and-run.md) | The one-command flow, starting and stopping a VM, manual stages |
| [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks prove |
-| [iPadOS Guests](Guides/ipados.md) | Running iPadOS from an iPad restore IPSW instead of iOS |
-| [Other iPhone Models](Guides/iphone-models.md) | Running iOS from an iPhone 16 Pro, 17, 17 Pro, Air or other model's IPSW |
+
+## Machines
+
+| Page | Use it for |
+| --- | --- |
+| [Firmware Preparation](Guides/firmware-preparation.md) | The GPU driver restore, kernelcache mixes for newer cloudOS, remote linking |
+| [Templates](Guides/templates.md) | How `vm create` reuses one restore, offline trim, setup boot and slimming |
+| [Building and Finding Templates](Guides/template-building.md) | Turning a VM into a template, `vm template find`, templates in Launchpad |
+| [Create Many Machines](Guides/many-machines.md) | `vm create-bulk` from a plist |
+| [Device Name and Clock](Guides/device-name-and-clock.md) | What the guest takes from the VM name and the Mac's clock |
+| [Library, Firmware and Backups](Guides/library-and-backups.md) | Where machines and caches live, downloads, clones and exports |
+| [Sharing Disk Space](Guides/sharing-disk-space.md) | `vm rebase` for VMs restored separately |
+| [Snapshots](Guides/snapshots.md) | Saving a stopped VM's disk state and reverting to it |
| [Package Environment](Guides/package-environment.md) | Installing and removing a package manager in the VM |
+| [Persistent Shader Caches](Guides/shader-cache.md) | Enabling shader caches on an existing VM |
+
+## Devices
+
+| Page | Use it for |
+| --- | --- |
+| [Other iPhone Models](Guides/iphone-models.md) | Running iOS from an iPhone 16 Pro, 17, 17 Pro, Air or other model's IPSW |
+| [iPadOS Guests](Guides/ipados.md) | Running iPadOS from an iPad restore IPSW instead of iOS |
+
+## Networking
+
+| Page | Use it for |
+| --- | --- |
+| [Networking](Guides/networking.md) | Network modes, choosing one, unplugging a running VM |
+| [Tunnel Mode](Guides/network-tunnel.md) | A Mac behind a VPN or proxy app |
+| [MAC and IP Addresses](Guides/network-addresses.md) | The saved MAC, leases held by old MACs, fixed addresses |
+| [Port Forwarding](Guides/network-port-forwarding.md) | Carrying a port on the Mac into the guest |
+| [Names on the Network](Guides/network-names.md) | The guest's `.local` name and this Mac's name in the guest |
+| [Machines Reaching Each Other](Guides/network-peers.md) | `nat` machines on one shared network |
+
+## Reference
+
+| Page | Use it for |
+| --- | --- |
+| [Launchpad Command Line](Guides/launchpad-cli.md) | Driving Launchpad with `vphone-launchpad-cli` |
+| [Core Bundles and Local Builds](Guides/core-bundles.md) | Binding machines to bundles, installing and comparing local builds |
+| [Bundle Integration](Guides/bundle-integration.md) | What `VPhone.bundle` contains and how an app integrates it |
+
+## Help
+
+| Page | Use it for |
+| --- | --- |
| [Troubleshooting](Guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |
-| [Networking](Guides/networking.md) | Network modes, fixed addresses, port forwarding, and `tunnel` for a Mac behind a VPN or proxy |
-| [Launchpad Command Line](Guides/launchpad-cli.md) | Installing and testing a local build with `vphone-launchpad-cli` |
## Translations
diff --git a/README.md b/README.md
index 1b07fa47..02618040 100644
--- a/README.md
+++ b/README.md
@@ -96,15 +96,18 @@ vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
| --- | --- |
| [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 |
+| [Create and Run](Documents/Guides/create-and-run.md) | The creation process, starting and stopping a VM |
+| [Templates](Documents/Guides/templates.md) | Reusing one restore for many VMs, slimming the guest |
+| [Library and Backups](Documents/Guides/library-and-backups.md) | Where VMs live, clones and exports |
| [Snapshots](Documents/Guides/snapshots.md) | Save a stopped VM's disk state and revert to it |
| [Compatibility](Documents/Guides/compatibility.md) | Verified firmware pairings |
| [iPadOS Guests](Documents/Guides/ipados.md) | Run iPadOS instead of iOS |
| [Other iPhone Models](Documents/Guides/iphone-models.md) | Run iOS from another iPhone model's IPSW |
| [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 |
-| [Networking](Documents/Guides/networking.md) | Network modes, and `tunnel` for a Mac behind a VPN or proxy |
+| [Networking](Documents/Guides/networking.md) | Network modes, addresses, port forwarding, and `tunnel` for a Mac behind a VPN or proxy |
| [Launchpad Command Line](Documents/Guides/launchpad-cli.md) | Install and test a local build with `vphone-launchpad-cli` |
+| [All Guides](Documents/README.md) | Every guide, grouped by subject |
| [Contributing](Documents/README.md#for-contributors) | Project structure, building from source, research notes |
If these do not solve your problem, [open an issue](https://github.com/Lakr233/vphone-cli/issues).
diff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.md
index 11fe7b2f..205e0ab2 100644
--- a/Research/Host/machine_templates.md
+++ b/Research/Host/machine_templates.md
@@ -6,7 +6,7 @@ from it with `clonefile(2)` and a new identity (see
[machine identity and clone](machine_identity_and_clone.md)), so a second
machine for the same firmware costs a clone and a few hundred MB of first-boot
writes instead of a 20 GB restore. User-facing behavior is in
-[Create and run](../../Documents/Guides/create-and-run.md#templates). What
+[Create and run](../../Documents/Guides/templates.md). What
templates save against the alternatives that were measured, and the build and
clone timings, are in [disk space](disk_space.md).
diff --git a/Skills/vphone-guest-control/references/finding-docs.md b/Skills/vphone-guest-control/references/finding-docs.md
index 8fae44d7..63caf94c 100644
--- a/Skills/vphone-guest-control/references/finding-docs.md
+++ b/Skills/vphone-guest-control/references/finding-docs.md
@@ -26,7 +26,7 @@ note's command lines.
| --- | --- |
| `vphone-vm` killed before a window opens; AMFI; "Research Guests" | `Documents/Guides/host-setup.md`, `Documents/Guides/troubleshooting.md`, `Research/Host/macos27_m6_amfi.md` |
| Launchpad/bundle version mismatch, which Launchpad is notarized | `Documents/Downloads/README.md`, `Documents/Guides/bundle-integration.md` |
-| `vm create` failed at a step; restore or DFU trouble | `Documents/Guides/create-and-run.md`, `Documents/Guides/compatibility.md`, `Research/Restore/native_restore_architecture.md`, `Research/Restore/virtual_dfu_probe.md` |
+| `vm create` failed at a step; restore or DFU trouble | `Documents/Guides/create-and-run.md`, `Documents/Guides/firmware-preparation.md`, `Documents/Guides/compatibility.md`, `Research/Restore/native_restore_architecture.md`, `Research/Restore/virtual_dfu_probe.md` |
| Which iPhone IPSW pairs with which cloudOS | `Documents/Guides/compatibility.md`; `vphone-cli fw catalog` (via `exec`) for what exists now |
| Guest boots to a black screen or loops | `Documents/Guides/troubleshooting.md`, `Research/Patches/hv_vmm_present_usermode_xrefs.md`, `Research/Kernel/kernel_jb_patch_notes.md` |
| `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` in an app | `Documents/Guides/troubleshooting.md`, `Research/KernelCustomFirmwarePatches/README.md` |
@@ -45,13 +45,16 @@ note's command lines.
| Machine identity, clone behaving like the same device | `Research/Guest/machine_identifier_storage_analysis.md` |
| What a patch does, whether it is on, why a preset differs | `Research/0_binary_patch_comparison.md`, `Research/KernelCustomFirmwarePatches/README.md` |
| Which binary does what in the bundle | `Research/Host/host_binary_split.md`, `Documents/Guides/bundle-integration.md` |
-| Launchpad command line | `Documents/Guides/launchpad-cli.md` |
+| Launchpad command line; Core Bundles and local builds | `Documents/Guides/launchpad-cli.md`, `Documents/Guides/core-bundles.md` |
## By subject
- **User guides** (`Documents/Guides/`): `host-setup`, `create-and-run`,
- `compatibility`, `troubleshooting`, `package-environment`,
- `bundle-integration`, `launchpad-cli`. `Documents/README.md` indexes them.
+ `firmware-preparation`, `templates`, `template-building`, `many-machines`,
+ `library-and-backups`, `sharing-disk-space`, `snapshots`, `networking` and
+ its `network-*` pages, `compatibility`, `troubleshooting`,
+ `package-environment`, `bundle-integration`, `launchpad-cli`,
+ `core-bundles`. `Documents/README.md` indexes them.
- **Research index:** `Research/README.md` lists every note by subject
(firmware, kernel, restore, host, guest, history).
- **Patch inventory:** `Research/0_binary_patch_comparison.md` is canonical for
diff --git a/Skills/vphone-guest-control/references/install.md b/Skills/vphone-guest-control/references/install.md
index 8c7f3ca2..511db72f 100644
--- a/Skills/vphone-guest-control/references/install.md
+++ b/Skills/vphone-guest-control/references/install.md
@@ -118,7 +118,7 @@ paths are resolved by the CLI. Installing does not move existing machines: bind
one with `vm set-bundle <name> <version> --update-environment`, or create one
with `vm create <name> --bundle <version>`. Each rebuild installs as a new
version; remove old ones no machine uses. To compare two builds, see
-`Documents/Guides/launchpad-cli.md` (Comparing two builds).
+`Documents/Guides/core-bundles.md` (Comparing two builds).
## When an install step fails
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
index 314028a9..c7570f91 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
@@ -55,7 +55,7 @@ kexts whose imports have no counterpart there (15 donor kexts instead of 18).
- A kmutil of the base's `builderLayout`: macOS 26.4 or later for the iOS 26 bases,
macOS 15 or 26.0 to 26.3 for the iOS 18 ones. A Mac with the other layout
links over ssh on one that has it (`VPHONE_KMUTIL_SSH`, see
- `Documents/Guides/create-and-run.md`).
+ `Documents/Guides/firmware-preparation.md`).
- The kmutil of macOS 27 links `kernel-last` too, but keeps every kext's
`__auth_stubs`. After the link, `KernelCollectionStubCalls` makes the calls
through them direct again and seals corecrypto's FIPS HMAC again, so the