Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs: describe the split, and stop promising an allowlist we cannot deliver

Lakr86d2b508bf82
diff --git a/AGENTS.md b/AGENTS.md
index 66dd50f6..2d4fba28 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,27 +47,36 @@ See `research/` for detailed firmware pipeline, component origins, patch breakdo
Makefile # Single entry point — run `make help`
sources/
-├── vphone.entitlements # Private API entitlements (5 keys)
-└── vphone-cli/ # Swift 6.0 executable (pure Swift, no ObjC)
- ├── main.swift # Entry point — NSApplication + AppDelegate
+├── vphone.entitlements # Private API entitlements (7 keys) — signed ONTO vphone-vm ONLY
+│
+├── vphone-cli/ # Entry point. NO entitlements, so it always launches.
+│ │ # Argument parsing + orchestration; spawns the others.
+│ ├── main.swift # Parses, and forwards `boot` to vphone-vm
+│ ├── VPhoneCLI.swift # Root command, patch-firmware/patch-component
+│ ├── VPhoneFWCLI.swift # Firmware subcommands
+│ ├── VPhoneSetupCLI.swift # Setup subcommands
+│ ├── VPhoneRestoreCLI.swift # Restore subcommands
+│ ├── VPhoneVMCLI.swift # VM subcommand group
+│ ├── VPhoneVMCreateCLI.swift # VM create
+│ ├── VPhoneVMLaunchCLI.swift # VM launch
+│ ├── VPhoneVMTransferCLI.swift # VM transfer
+│ ├── VPhoneCreateOptions.swift # Create-flow option set
+│ ├── VPhoneCreateOrchestrator.swift # Native `vm create` pipeline driver
+│ ├── VPhoneFirmwareSelection.swift # Interactive firmware picker
+│ ├── VPhoneVMSelection.swift # Interactive VM picker
+│ └── VPhoneProgressBar.swift # Terminal progress rendering
+│
+├── vphone-vm/ # The ONLY entitled binary — a parse and a run loop
+│ └── main.swift # VPhoneBootCLI.parseOrExit() → VPhoneGuestApp.run()
+│
+├── vphone-letmein/ # Opens a short AMFI window so vphone-vm can exec
+│ └── main.c # Plain C; Foundation + libobjc only
+│
+└── VPhoneVMKit/ # Everything that touches a running guest
+ ├── VPhoneGuestApp.swift # NSApplication wiring (keeps the entry point logic-free)
├── VPhoneAppDelegate.swift # App lifecycle, SIGINT, VM start/stop
- ├── VPhoneBuildInfo.swift # Auto-generated build-time commit hash
├── VPhoneHostControl.swift # Unix-socket automation server (one JSON line in/out)
- │
- ├── CLI/ # ArgumentParser command tree + interactive pickers
- │ ├── VPhoneCLI.swift # Root command and global options
- │ ├── VPhoneFWCLI.swift # Firmware subcommands
- │ ├── VPhoneSetupCLI.swift # Setup subcommands
- │ ├── VPhoneRestoreCLI.swift # Restore subcommands
- │ ├── VPhoneVMCLI.swift # VM subcommand group
- │ ├── VPhoneVMCreateCLI.swift # VM create
- │ ├── VPhoneVMLaunchCLI.swift # VM launch
- │ ├── VPhoneVMTransferCLI.swift # VM transfer
- │ ├── VPhoneCreateOptions.swift # Create-flow option set
- │ ├── VPhoneCreateOrchestrator.swift # Native `vm create` pipeline driver
- │ ├── VPhoneFirmwareSelection.swift # Interactive firmware picker
- │ ├── VPhoneVMSelection.swift # Interactive VM picker
- │ └── VPhoneProgressBar.swift # Terminal progress rendering
+ ├── VPhoneBootCLI+VirtualMachine.swift # resolveOptions() — the half that needs Virtualization
│
├── VM/ # VM core
│ ├── VPhoneVirtualMachine.swift # @MainActor VM configuration and lifecycle
@@ -79,8 +88,7 @@ sources/
│ ├── VPhoneControl.swift # Host-side vsock client for vphoned (length-prefixed JSON)
│ ├── VPhoneControlApps.swift # Installed apps — list and launch
│ ├── VPhoneControlKeychain.swift # Keychain dump
- │ ├── VPhoneControlSystem.swift # Device, battery, location, devmode
- │ └── VPhoneInstallPackage.swift # Package installation over vsock
+ │ └── VPhoneControlSystem.swift # Device, battery, location, devmode
│
├── Interface/ # Window & UI
│ ├── VPhoneWindowController.swift # @MainActor VM window management + toolbar
@@ -147,9 +155,11 @@ research/ # Detailed firmware/patch documentation
### Key Patterns
+- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-letmein` opens a window when it does. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.
+- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — and decides once per command whether an AMFI window is needed, by running `vphone-vm --help` and looking for SIGKILL. Never spawn the guest directly.
- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.
-- **App lifecycle:** `main.swift` → `NSApplication` + `VPhoneAppDelegate`. CLI args parsed before run loop. AppDelegate drives VM start/window/shutdown.
-- **Configuration:** `ArgumentParser` → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.
+- **App lifecycle:** `vphone-vm/main.swift` → `VPhoneGuestApp.run()` → `NSApplication` + `VPhoneAppDelegate`. Entry points hold no logic.
+- **Configuration:** `ArgumentParser` → `VPhoneBootCLI` (in `VPhoneCore`, parsed by both binaries) → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.
- **Guest daemon (vphoned):** ObjC daemon inside iOS VM, vsock port 1337, length-prefixed JSON protocol. Host side is `VPhoneControl` with auto-reconnect.
- **Menu system:** `VPhoneMenuController` + per-menu extensions (Keys, Type, Location, Connect, Install, Record).
- **File browser:** SwiftUI (`VPhoneFileBrowserView` + `VPhoneFileBrowserModel`) in `NSHostingController`. Search, sort, upload/download, drag-drop via `VPhoneControl`.
diff --git a/README.md b/README.md
index 22212fe8..1c09736b 100644
--- a/README.md
+++ b/README.md
@@ -137,7 +137,7 @@ Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take ef
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after
```
-**Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont** (leaves AMFI enabled system-wide).
+**Option B — keep SIP on (debug-only relaxed) and let `vphone-cli` open a window per launch** (leaves AMFI enabled the rest of the time).
In Recovery:
@@ -146,12 +146,30 @@ csrutil enable --without debug
csrutil allow-research-guests enable
```
-Then reboot into macOS and:
+Then reboot into macOS. There is nothing else to set up: `vphone-cli` carries
+no entitlements and always launches, so when it starts a guest it notices that
+amfid will not accept `vphone-vm`, opens a window with `vphone-letmein` (one
+sudo prompt), and closes it once the guest is running.
+
+To do it by hand — worth it while working on `vphone-vm`, where one sudo beats
+a prompt per run:
```bash
-vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds
+make letmein # open (sudo)
+make letmein_status # check
+make letmein_off # close
```
+> **Be honest about what this does.** It is a global switch, not an allowlist:
+> while the window is open, amfid reports *every* signature it checks as valid
+> and Apple-signed. That cannot be narrowed to one path or one binary — a
+> per-validation decision needs Apple-private debugger entitlements. What can
+> be narrowed is time, which is why the automatic path holds the window only
+> for the length of one launch. It is also memory-only: a reboot clears it.
+>
+> `vphone-letmein` replaces the old `amfidont` helper, which was a pip package
+> and is no longer used.
+
## Tested Environments
| Host | iPhone | CloudOS |
@@ -179,7 +197,7 @@ vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfido
## FAQ
-**`zsh: killed ./vphone-cli`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1` or `amfidont`).
+**`zsh: killed ./vphone-vm`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1`, or let `vphone-cli` open a window for you). Note this cannot happen to `vphone-cli` itself: it carries no entitlements, so if *it* is being killed, something else is wrong.
**`Virtualization is not available on this hardware`** — your Mac is itself a VM; PV=3 guest boot can't nest. Use a non-nested macOS 15+ host.
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index c51be030..b94cebd8 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -787,7 +787,8 @@ cache rebuild.
- it can attach to `/usr/libexec/amfid`
- the initial path allow rule failed because `AMFIPathValidator` reports URL-encoded paths (`/Volumes/My%20Shared%20Files/...`)
- rerunning `amfidont` with the encoded project path and the release-binary CDHash allows the signed release `vphone-cli` to launch
- - this workflow is now packaged as `make amfidont_allow_vphone` / `scripts/start_amfidont_for_vphone.sh`
+ - this workflow was packaged as `make amfidont_allow_vphone` / `scripts/start_amfidont_for_vphone.sh`
+ - **superseded 2026-09-23.** `amfidont` is gone, and so is the path/CDHash allowlist it provided — on macOS 26 amfid carries `com.apple.developer.hardened-process`, which gates the debugger operations a per-validation decision needs. `vphone-letmein` replaces it with a global switch held open only for the length of one launch, and `vphone-cli` (now unentitled, so it always starts) drives that itself. The URL-encoding detail above no longer applies: nothing matches on paths any more. See `sources/vphone-letmein/main.c`.
- With launch policy bypassed, `make boot_dfu` advances into VM setup, emits `vm/udid-prediction.txt`, and then fails with `VZErrorDomain Code=2 "Virtualization is not available on this hardware."`
- `VPhoneAppDelegate` startup failure handling was tightened so these fatal boot/DFU startup errors now exit non-zero; `make boot_dfu` now reports `make: *** [boot_dfu] Error 1` for the nested-virtualization failure instead of incorrectly returning success.
- The host itself is a nested Apple VM (`Model Name: Apple Virtual Machine 1`, `kern.hv_vmm_present=1`), so the remaining blocker is lack of nested Virtualization.framework availability rather than firmware patching or AMFI bypass.
diff --git a/research/host_binary_split.md b/research/host_binary_split.md
new file mode 100644
index 00000000..3d310934
--- /dev/null
+++ b/research/host_binary_split.md
@@ -0,0 +1,144 @@
+# The host binary split: vphone-cli / vphone-vm / vphone-letmein
+
+> 2026-09-23, branch `vphone-intg-update`.
+> Supersedes the single-executable layout and the `amfidont` helper.
+
+## The problem it solves
+
+All seven private entitlements used to be signed onto `vphone-cli` — the binary
+a user types. amfid will not accept Apple-private entitlements on an ad-hoc
+signature, so the kernel killed the entry point at exec. `vphone-cli --help`
+printed nothing and exited 137.
+
+That is a chicken-and-egg: the tool could not run in order to arrange the
+conditions under which it could run. The only way out was to leave a bypass
+daemon running all the time, so that every process on the machine was being
+told that every signature was valid, for as long as the machine was up.
+
+## The shape now
+
+| binary | entitlements | what it is |
+| --- | :---: | --- |
+| `vphone-cli` | **none** | argument parsing and orchestration. Launches anywhere. |
+| `vphone-vm` | **all 7** | a parse and an `NSApplication` run loop over `VPhoneVMKit`. |
+| `vphone-letmein` | none (needs root) | opens an AMFI window. Plain C. |
+
+`vphone-cli` is now always able to start, which is what lets it do something
+about amfid instead of being the thing amfid stops. When it is asked for a
+guest it hands the boot to `vphone-vm`, opening a window around the exec if it
+has to and closing it immediately after.
+
+The compensating control moved from **scope** to **time**. The old helper
+claimed a path/CDHash allowlist; that is not reproducible on macOS 26, because
+deciding per-validation means interrupting amfid, and amfid carries
+`com.apple.developer.hardened-process`, which gates exactly those debugger
+operations behind Apple-private entitlements. So the switch is global while it
+is open — and the answer is to keep it open for one exec rather than all day.
+
+**Do not describe `vphone-letmein` as scoped to a binary or a path.** It is not.
+
+## Why the split was cheap
+
+The CLI/VM boundary was already a process boundary. `vm launch` and four sites
+in the create orchestrator all spawned the running executable through
+`VPhoneResources.runningExecutable()`. The change is mostly *what* they spawn.
+
+## Things that are easy to get wrong
+
+### `Bundle.main.executableURL` cannot find this process any more
+
+It reads `CFBundleExecutable`, which is now `vphone-vm`. Ask it while running
+`vphone-cli` — in the same `Contents/MacOS` — and it answers `vphone-vm`.
+`runningExecutable()` uses `_NSGetExecutablePath`, which is the path the kernel
+exec'd and owes nothing to any plist.
+
+### `CFBundleExecutable` is `vphone-vm`, deliberately
+
+The `.app` is never opened through Launch Services; every caller runs a binary
+inside it directly. It exists to give the process that becomes an
+`NSApplication` a bundle — icon, `LSUIElement`, the `NSLocation*UsageDescription`
+strings. That process is `vphone-vm`.
+
+### An unentitled `vphone-vm` is worse than a broken one
+
+It launches perfectly. The AMFI probe therefore concludes nothing is wrong, the
+boot proceeds, and it fails much later trying to create a PV=3 machine — far
+from the cause. A bare `swift build -c release` leaves exactly that state
+behind, because only `make build` / `scripts/build.sh` sign. Both now verify
+the entitlements actually landed and fail if they did not. This was found by
+walking into it.
+
+### Bridged networking nearly broke silently
+
+`availableBridgeInterfaces()` returns an empty list without
+`com.apple.vm.networking` — which `vphone-cli` no longer has. The old code read
+that as "this host has no bridgeable interfaces" and rejected `--network
+bridged` on a machine full of them. An empty list is now treated as *cannot
+tell*: the requested name is recorded and `vphone-vm`, which is entitled,
+validates it at boot where the error can name the real problem. With no name
+given and nothing to enumerate, `bridgeInterfaceMustBeNamed` says so.
+
+This is the general hazard of the split — **anything that read host state
+through an entitled API from the CLI side is now reading it unprivileged.**
+Nothing else in `VPhoneCore` does, but new code might.
+
+## The probe
+
+`vphone-vm --help`. amfid decides at exec, before any of the target's own code
+runs, so a `--help` that never prints is the same refusal a real boot would
+hit. It costs nothing and touches no VM state. A refusal is `SIGKILL`, which
+Foundation reports as termination status 9. Any *other* non-zero exit is raised
+rather than escalated into a sudo prompt — we only ask for root on the one
+signature we recognise.
+
+`VPHONE_LETMEIN=auto|always|never`, and `--let-me-in` on `vm launch`. `never`
+still probes: it means "do not open a window", not "do not tell me why", and
+skipping the probe would hand the user a bare exit 9 with no explanation, which
+is the failure this path exists to remove.
+
+## `--hold` changed meaning
+
+Upstream `exec --hold N` restored the patch after N seconds and returned
+immediately, leaving the child running. That loses the guest's exit status and
+every signal path to it, so `vphone-cli` could not report or cancel a boot.
+
+Now `--hold N` restores after N seconds and *keeps supervising*: the window is
+still only one launch long, but the guest's exit status and signals still reach
+the caller. The old behaviour is `--hold N --detach`. `SIGINT`/`SIGTERM`/`SIGHUP`
+are also forwarded to the child before the supervisor leaves — without that, a
+Ctrl-C took down the supervisor and left the guest parentless, which looks
+exactly like a hang.
+
+## Verified, and not
+
+**Verified on 2026-09-23** (AMFI window closed, no sudo available):
+
+| | |
+| --- | --- |
+| `vphone-cli` entitlements | 0 keys |
+| `vphone-vm` entitlements | 7 keys |
+| `vphone-cli --help` | exits 0 and prints |
+| `vphone-vm --help` | exits 137 — amfid refuses it, as expected |
+| probe + `VPHONE_LETMEIN=never` | reports the refusal in full, never touches sudo |
+| probe + `auto` | builds `sudo …/vphone-letmein exec --hold 10 -- …/vphone-vm --config …`, confirmed in the process tree |
+| sibling resolution | resolves through the `.build/release` symlink to the real `Products/Release` directory |
+| entitlement guard | fails as required on an unentitled binary |
+| `VPhoneCoreTests` | 130/130 |
+| `vphone-letmein` | builds `-Wall -Wextra` clean; `otool -L` shows only Foundation, libSystem, libobjc |
+
+**Not verified — needs root and a real guest:**
+
+1. **Whether `vphone-vm` can actually start a VM holding the entitlements
+ alone.** Everything here rests on it. Nothing about the split is proven
+ until a guest boots.
+2. **`--hold 10` — is 10 seconds right?** A guess. Too short and the exec is
+ still being validated when the window shuts; too long and it is open for no
+ reason. Measure it.
+3. **The `auto` path end to end**, including the sudo prompt, `--hold`
+ restoring while the guest keeps running, and Ctrl-C reaching the guest.
+4. **Location and TouchID**, which depend on TCC attributing the usage strings
+ to `vphone-vm`. It is `CFBundleExecutable`, so it should — but TCC's view of
+ a binary inside someone else's bundle is worth confirming rather than
+ assuming.
+5. **Bridged networking**, now that the name is validated at boot instead of at
+ config time.