Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Merge main into vphoned HTTP API branch

Lakr0d2ddd43e447
diff --cc AGENTS.md
index 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 Rules
diff --cc README.md
index ce2fef74,66df0433..edb746a1
--- a/README.md
+++ b/README.md
@@@ -58,206 -20,46 +20,56 @@@ vphone-cli vm create myphone
vphone-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.
## Acknowledgements
diff --cc scripts/build.sh
index 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.swift
index 827d0914,d0b323e5..099973ed
--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
@@@ -80,15 -80,11 +80,15 @@@ extension CryptexFilesystemPatcher
try 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.swift
index ac90eecc,21617652..e9a49c21
--- a/sources/vphone-cli/VPhoneCFWInstaller.swift
+++ b/sources/vphone-cli/VPhoneCFWInstaller.swift
@@@ -212,12 -238,12 +238,14 @@@ struct VPhoneCFWInstaller
let 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(