Run a virtual iPhone on an Apple Silicon Mac.
Swift
Merge main into vphoned HTTP API branch
Lakr0d2ddd43e447
diff --cc AGENTS.mdindex 135c1504,6366543a..2adfb096--- a/AGENTS.md+++ b/AGENTS.md@@@ -9,10 -9,10 +9,10 @@@ Virtual iPhone boot tool using Apple's- **Boot (DFU):** `make boot_dfu`- **All targets:** `make help`- **AMFI refuses `vphone-vm`?** `make amfi_allow` (asks for root). Re-run it after every build — it allowlists cdhashes. `make amfi_status` to look, `make amfi_off` to revert. See Key Patterns.- - **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`sources/MobileRecoveryCore`, `sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/p2_restore_off_python.md`.- - **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in README's "SIP/AMFI Relaxation"; neither is installed by this project.+ - **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`sources/MobileRecoveryCore`, `sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/restore/p2_restore_off_python.md`.+ - **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in `docs/guides/host-setup.md`; neither is installed by this project.- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic). This package's own manifest is `swift-tools-version:6.0`, but the **toolchain floor is Swift 6.2**: `libcapstone-spm` declares 6.2 so that it can reach `CSetting.disableWarning` instead of `.unsafeFlags`, which is what lets it be depended on by version at all.-- **Dependencies:** seven SwiftPM packages, every one resolved by URL and **every one by version** — there is no `vendor/` directory, no `branch:` requirement, and `Package.resolved` pins fourteen once transitives are counted. The only git submodule is `scripts/repos/insert_dylib`, a build-time test reference. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.+- **Dependencies:** Host and guest SwiftPM packages resolve dependencies by URL and version; `Package.resolved` pins the full graphs. The only git submodule is `scripts/repos/insert_dylib`, a build-time test reference. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.- **Tiers.** Three environments run code here and the rules differ. **build** (the machine that builds the `.app`) may use Xcode, `xcrun`, clang, swift, git and Homebrew. **dist** (the shipped `.app`, on a clean macOS) may use `/usr/lib`, `/System` and the bundle — nothing else, no `PATH` lookup. **guest** (inside the VM) is out of host self-containment scope. Every script declares its tier on **line 2** (`# vphone-tier: dist`); `scripts/dist_manifest.sh` reads those and is what `build.sh` and `make bundle` stage from, so a script that declares nothing ships nowhere. `make check-aux` gates all of it. The dist tier's registered-exception list is **empty** and a release requires it to stay that way.## Workflow Rulesdiff --cc README.mdindex ce2fef74,66df0433..edb746a1--- a/README.md+++ b/README.md@@@ -58,206 -20,46 +20,56 @@@ vphone-cli vm create myphonevphone-cli vm launch myphone```+To expose the guest HTTP and WebSocket API on the host for local tools or an+app using `VPhoneKit`, opt in when launching:+- ```bash++```sh+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765- curl http://127.0.0.1:8765/openapi.json+```+- The API is off by default. See [the API contract](research/vphoned_http_api.md)++The guest runs `icli` commands through the API. See the [API design and usage](research/vphoned_http_api.md)+for routes, WebSocket messages, and the Swift Kit client.+- The single supported firmware mode is JB. Creation installs vphoned and the- required system patches, then checks that vphoned connects. It does not install- a package manager, SSH server, or user bootstrap.-- ## Commands-- `vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.-- ### Manage-- ```bash- vphone-cli vm list # list VMs (--json for scripting)- vphone-cli vm info myphone # show one VM- vphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options)- vphone-cli vm config myphone --cpu 8 --memory 8192- vphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity- vphone-cli vm export myphone --out myphone.tzst # zstd fast by default (--max = xz -9); --out may be a dir (auto-names <vm>.tzst/.txz); skips restore dir + staging files- vphone-cli vm import myphone.tzst --name restored- vphone-cli vm rename myphone iphone16- vphone-cli vm delete iphone16- ```-- ### Build a VM manually (what `vm create` automates)-- ```bash- vphone-cli vm new myphone # 1. empty bundle- vphone-cli fw prepare myphone --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw # 2. merge IPSWs- vphone-cli fw patch myphone # 3. patch the JB boot chain-- vphone-cli vm launch myphone --dfu & # 4. boot into DFU (background)- vphone-cli restore myphone # fetch a ticket and DFU restore- vphone-cli vm stop myphone # stop the DFU boot-- vphone-cli cfw install myphone # 5. install CFW (host-mount; asks for sudo)- vphone-cli vm launch myphone # 6. first boot- ```-- Update to a newer iOS by pointing `fw prepare` at an IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.-- The restore command runs in `vphone-cli`'s own process. It drives vendored- libirecovery and idevicerestore directly — no external restore tool, no setup- step before the first one works. Use `restore --get-shsh` separately if you- need to save a ticket, then add `--offline` to restore from that `.shsh`- instead of asking Apple for a fresh one.-- ## Firmware Mode-- The CLI exposes one firmware mode: JB. There is no `--variant` choice.-- See [`research/0_binary_patch_comparison.md`](./research/0_binary_patch_comparison.md) for the per-component breakdown.-- ## Running & Connecting+ `vm create` prepares and patches firmware, restores the VM, installs the JB system changes and vphoned, then boots once to check a real vphoned ping. **It stops that verification boot before returning.** Run `vm launch` to keep using the VM. The create flow needs network access for Apple's restore ticket and asks for administrator authentication during CFW installation.- - **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (password `alpine`)- - **VNC:** `vnc://<vm-ip>:5901`+ For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both reached the lock screen and answered vphoned ping with cloudOS **26.4 (23E5207q)**. See [compatibility and evidence](docs/guides/compatibility.md); other firmware combinations are not implied by these results.- ## Locations+ ## Install or build- Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable. Redirect the whole tree with `$VPHONE_ROOT`:+ A distributed `.app` uses macOS system tools and its own bundled binaries; it does not need Homebrew, Python, or Xcode to run. Building from source does not install a separate runtime environment.- | Path | Contents |- | ----------------- | -------------------------------------------------------------------------------------------- |- | `~/.vphone/` | The per-user data root — override the entire location with `$VPHONE_ROOT`. |- | `~/.vphone/VMs/` | VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`. |- | `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. |- | `~/.vphone/tools/`| Cached APFS seal-volume artifacts used by firmware patching. |+ Building from source needs Xcode, including its iPhoneOS SDK for vphoned:- Precedence: the per-item override `$VPHONE_LIBRARY_ROOT` wins over `$VPHONE_ROOT`, which wins over the `~/.vphone` default. The `ipsws/`, `tools/`, and `debs/` caches always sit directly under whichever root is active.-- ## SIP/AMFI Relaxation-- **Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).**-- In Recovery (long-press power → Terminal):-- ```bash- csrutil disable- csrutil allow-research-guests enable- ```-- Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):-- ```bash- sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after- ```-- This is still the simplest path, and the only one that needs nothing running- alongside the VM: with AMFI relaxed, `vphone-vm` launches on its own.-- **Option B — keep SIP on (debug-only relaxed) and allowlist this build** (AMFI- stays enabled the rest of the time, and for every binary you did not allow).-- In Recovery:-- ```bash- csrutil enable --without debug- csrutil allow-research-guests enable- ```-- Then reboot into macOS and run:-- ```bash- make amfi_allow # asks for root; run it again after every build- make amfi_status # show the allowlist, and whether this host can carry one- make amfi_off # remove it and restart amfid clean+ ```sh+ git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+ cd vphone-cli+ make build+ .build/release/vphone-cli --help```- That runs `vphone-amfi-allow`, which is built from this repository's own C and- ships inside the `.app`. It writes two things:-- * the cdhashes of **both** copies of `vphone-vm` into- `/Library/Preferences/com.apple.security.coderequirements.plist`, which AMFI- already reads — this is a feature amfid ships, not a hole;- * one byte of amfid's **heap**, to flip the `_isRunningInternalBuild` flag that- makes it consult that file in the first place.-- Both, because `make boot` launches both: `boot_binary_check` runs- `.build/release/vphone-vm` and the boot itself runs the one inside the `.app`.- They sign under different identifiers and hash differently, so allowing one- covers exactly half the flow.-- **Re-run it after every build.** It allowlists cdhashes, and those change with- every signature — including a bare `swift build`.-- `vphone-vm` is the binary to allow. `vphone-cli` carries no entitlements and- always launches, so its cdhash is not the one you want.-- > **Be clear about what this allows.** It is an allowlist keyed on cdhash:- > amfid keeps enforcing for every binary you did not name. `make amfi_off`- > removes the file and restarts amfid.- >- > The one byte is in amfid's heap, not its `__TEXT`, and that is the whole- > reason this works. Earlier attempts patched the code — `vphone-letmein`- > overwrote the `ldrb` in `-[AMFIPathValidator_macos validateWithError:]`, and- > LLDB-based tools plant a `BRK` for a breakpoint. Both leave a dirty unsigned- > executable page, and on a host where `sysctl vm.cs_system_enforcement` reads- > 1 — as it does on macOS 27.0 (26A428), arm64e, with exactly the `csrutil`- > settings above — the kernel validates that page on the next fault, kills- > amfid, and takes the guest down with it. The sysctl is read-only at runtime,- > so no amount of care makes "patch the code" survive it. A heap write is not- > code, so enforcement has nothing to object to.-- ## Tested Environments-- | Host | iPhone | CloudOS |- | --------------- | --------------------- | --------------- |- | Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |- | Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |- | Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |- | Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |- | Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |- | Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |- | Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |- | Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |- | Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |- | Mac16,6 26.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_26.6.1_23G83` | `26.4-23E5207q` |- | Mac16,6 26.6.1 | `17,3_26.6.2_23G90` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |- | Mac16,6 26.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |- | Mac16,6 26.6.1 | `17,3_27.0_24A5408d` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_27.0_24A5418b` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_27.0_24A5424a` | `26.4-23E5207q` |- | Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |- | Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |-- ## FAQ-- **`zsh: killed ./vphone-vm`** — AMFI/debug restrictions aren't bypassed; see [SIP/AMFI Relaxation](#sipamfi-relaxation) — either `amfi_get_out_of_my_way=1` (Option A), or `make amfi_allow` for this build (Option B). If you ran it before your last build, run it again: the allowlist is keyed on cdhash, and signing changes that. 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.-- **Stuck on "Press home to continue"** — connect via VNC and right-click (two-finger click) to simulate the home button.-- **System apps won't install** — during iOS setup, don't pick Japan or the EU as your region (extra regulatory checks the VM can't satisfy); pick e.g. United States.-- **App crashes on launch with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`** — re-patch with `vphone-cli fw patch <name> --force-exc-guard`, then re-restore/install ([#291](https://github.com/Lakr233/vphone-cli/issues/291)). Always on for iOS 18 bases.+ `make build` signs and bundles the binaries. After every rebuild, a host using the AMFI allowlist must run `make amfi_allow` again because the signed cdhash changes. See [host setup](docs/guides/host-setup.md).- **Install a `.ipa`/`.tipa`** — use the running VM's Install menu (drag-drop or file picker).+ ## Everyday commands- **Do I need Homebrew, or Xcode, to use this?** — No. `vphone-cli` runs on a clean macOS 15+: everything it shells out to is in `/usr/bin`, `/bin`, `/usr/sbin` or `/sbin`, and everything else is inside the `.app`. `make check-aux` is the gate that keeps it that way — it walks the bundle's dependency closure, checks the bundle holds exactly what it is supposed to, scans every shipped script for a `PATH` lookup, and smoke-tests the binaries with `env -i PATH=/usr/bin:/bin`. Building from source needs Xcode for the iOS SDK used to compile vphoned.+ | Task | Command |+ | --- | --- |+ | List VMs | `vphone-cli vm list` |+ | Inspect a VM | `vphone-cli vm info myphone` |+ | Start its window | `vphone-cli vm launch myphone` |+ | Stop it | `vphone-cli vm stop myphone` |+ | Back it up | `vphone-cli vm export myphone --out myphone.tzst` |+ | Restore a backup | `vphone-cli vm import myphone.tzst --name restored` |+ | Inspect firmware pairings | `vphone-cli fw catalog` |+ | Check the host | `vphone-cli host preflight` |- **`cfw install` hangs re-signing a system binary (e.g. `Campo`), memory climbing unbounded** — this was a bug in `ldid-procursus` up to `2.1.5-procursus7`: `bytes(uint64_t)` called `__builtin_clzll(0)` with no zero-guard, which is undefined behavior, and on that build resolved to a `0`-length that underflowed an unsigned loop counter, so `ldid` span writing one byte at a time into a growing buffer instead of terminating. Any entitlements plist with an integer value of exactly `0` triggered it, and some real Apple system binaries have one. It cannot happen any more: signing is `vphone-cli sign`, in-process, and `ldid` is not installed, invoked or shipped.+ VMs and downloaded firmware live under `~/.vphone/` by default. `VPHONE_ROOT` relocates the tree; `VPHONE_LIBRARY_ROOT` overrides just the VM library. Use `vphone-cli <group> --help` for current command options.- ## Automation+ ## Documentation- `vphone-cli` exposes a host control socket (`<bundle>/vphone.sock`) for programmatic control — screenshots, touch, swipes, hardware keys, clipboard — each action returning an inline screenshot for AI-driven E2E testing. See [vphone-mcp](https://github.com/pluginslab/vphone-mcp) for an MCP server wrapping it.+ - [Documentation index](docs/README.md) — setup, workflows, compatibility, troubleshooting, and translations.+ - [Create and run a VM](docs/guides/create-and-run.md) — full flow, manual stages, storage, and vphoned.+ - [Research index](research/README.md) — patch inventory, firmware analysis, restore work, and historical notes.+ - [Patch inventory](research/0_binary_patch_comparison.md) — per-component patch breakdown and historical variant comparison. Only JB is exposed by the current CLI.## Acknowledgementsdiff --cc scripts/build.shindex f029d372,72665b45..8ec49c67--- a/scripts/build.sh+++ b/scripts/build.sh@@@ -173,15 -168,18 +168,19 @@@ mkdir -p "${RES}/scripts# .app carried build.sh, check_aux.sh and setup_tools.sh, the last of which runs# `brew install`. See scripts/dist_manifest.sh for the three tiers.zsh scripts/dist_manifest.sh | rsync -a --files-from=- scripts/ "${RES}/scripts/"--# Only vphoned ships into the guest; old build outputs may still contain++# Only vphoned and icli ship into the guest; old build outputs may still contain# binaries for the removed bootstrap and must not leak into the bundle.mkdir -p "${RES}/guest"cp -f .build/guest/vphoned "${RES}/guest/vphoned"+cp -f .build/guest/icli "${RES}/guest/icli"[[ -f .build/vphoned.signed ]] && cp -f .build/vphoned.signed "${RES}/vphoned.signed" || true- # README.md holds the Tested-Environments table used by `fw prepare`.- cp -f README.md "${RES}/README.md"- echo " bundled: scripts/ (dist tier), guest/vphoned, guest/icli, vphoned.signed, README.md"+ # The compatibility guide is the only documentation `fw prepare` reads at runtime.+ # Remove an old bundled README so it cannot silently become a stale data source.+ rm -f "${RES}/README.md"+ rm -rf "${RES}/docs"+ mkdir -p "${RES}/docs/guides"+ cp -f docs/guides/compatibility.md "${RES}/docs/guides/compatibility.md"-echo " bundled: scripts/ (dist tier), guest/vphoned, vphoned.signed, compatibility.md"++echo " bundled: scripts/ (dist tier), guest/vphoned, guest/icli, vphoned.signed, compatibility.md"# Re-sign: codesign seals Contents/Resources at sign time, so the earlier# bundle-step signature (made before these assets existed) is now stale —diff --cc sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swiftindex 827d0914,d0b323e5..099973ed--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift@@@ -80,15 -80,11 +80,15 @@@ extension CryptexFilesystemPatchertry FileManager.default.copyItem(at: vphonedBin, to: targetBin)try VPhoneSigner.sign(fileAt: targetBin,- options: try guestSigningOptions(- entitlements: vphonedSrc.appendingPathComponent("entitlements.plist")- )+ options: guestSigningOptions(+ entitlements: vphonedSrc.appendingPathComponent("entitlements.plist"),+ ),)try setMode(0o755, at: targetBin)+ let icli = try VPhoneGuestBinaries.resolve("icli")+ let targetIcli = target.appending(path: "/usr/bin/icli")+ try FileManager.default.copyItem(at: icli, to: targetIcli)+ try setMode(0o755, at: targetIcli)}/// Copy in the prebuilt guest daemon.diff --cc sources/vphone-cli/VPhoneCFWInstaller.swiftindex ac90eecc,21617652..e9a49c21--- a/sources/vphone-cli/VPhoneCFWInstaller.swift+++ b/sources/vphone-cli/VPhoneCFWInstaller.swift@@@ -212,12 -238,12 +238,14 @@@ struct VPhoneCFWInstallerlet entitlementsURL = resources.scriptsDir.appendingPathComponent("vphoned/entitlements.plist")let entitlements = try Data(contentsOf: entitlementsURL, options: .mappedIfSafe)try VPhoneSigner.sign(fileAt: staged,- options: .init(entitlements: entitlements, mergesExisting: true))+ options: .init(entitlements: entitlements, mergesExisting: true))try replace(staged, at: system.appendingPathComponent("usr/bin/vphoned"), mode: 0o755)+ let icli = try VPhoneGuestBinaries.resolve("icli")+ try replace(icli, at: system.appendingPathComponent("usr/bin/icli"), mode: 0o755)let signed = bundle.appendingPathComponent(".vphoned.signed")- if fm.fileExists(atPath: signed.path) { try fm.removeItem(at: signed) }+ if fm.fileExists(atPath: signed.path) {+ try fm.removeItem(at: signed)+ }try fm.copyItem(at: staged, to: signed)let daemon = resources.scriptsDir.appendingPathComponent("vphoned/vphoned.plist")try replace(daemon, at: system.appendingPathComponent(