LakrandClaude Opus 5
fe3cf50c6b
`cfw install` fails outright on a pristine 24A435 cache:
Patch site not found: checkTrustAndAuthorization: the prologue at
0x22406F814 neither seeds 0xE8008026 nor already reads
`pacibsp ; mov x0, #0 ; retab` — MIS has been rewritten
The cache really is pristine — the same run reports a first-time
`maxSlide 0x20000000 -> 0x0` and fresh lsd, libxpc and lockdown-mode
writes — so this is not the already-patched anchor that was fixed for
26.x. 24A435's checkTrustAndAuthorization matches neither shape.
Teaching the patcher the new shape would be the wrong fix. Even where it
applies, this patch stops an iOS 27 guest booting (issue #532): TXM
rejects the re-attested page, dyld cannot map libSystem, and initproc
never starts. Making it apply on 24A435 turns a failed install into a
guest that installs and then does not boot.
libmisfix.dylib already does the same job from userspace, and by the
better route — it steers the call instead of forging the return.
`vpWidenedOptions` passes `RespectUppTrustAndAuthorization = false`, and
libmis calls checkTrustAndAuthorization only when that flag is set, so
0xE8008026 is never produced and the success path still fills `info`
with the CdHash and entitlements its callers read. Nothing is written to
the cache, so there is nothing for TXM to reject. `cfw install` injects
it into installd and misagent.
So `standard` blocks the patch, and it is renamed dyld-cfw-mis_trust_auth
-> dyld-exp-mis_trust_auth as the naming rule requires for a patch the
standard preset leaves off. The patcher and the `cfw patch-mis-trust-auth`
verb are unchanged and still work when it is ticked on; `experimental`
is Kind=All and still turns it on.
The gap this leaves: libmisfix rides in installd and misagent, so the
hook covers installation, while an app signed with a free personal-team
certificate is launched by SpringBoard, which asks MIS itself. On a 26.x
base that launch can still hit 0xE8008026. Ad-hoc and ldid-signed apps
are unaffected — they carry no profile, so the online-authorization
branch is never reached — and paid teams never were. Closing it means
injecting the hook into SpringBoard, which needs SystemHook's posix_spawn
route rather than a load command.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
vphone-cli
Run a virtual iPhone on an Apple Silicon Mac.
vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtual machines, for security research, reverse engineering, and debugging.
- Graphical Window: Use the virtual iPhone's screen on your Mac, browse apps and files, and take screenshots and screen recordings.
- Custom Firmware: The system comes pre-patched, and you can install a package environment.
- Backup and Cloning: You can export, import, and clone VMs.
- Automation API: An optional local HTTP and WebSocket interface.
- No Extra Dependencies: Needs no Xcode, Python, or Homebrew at runtime.
For 1.x, see the 1.0.14 release. Version 2.x cannot start VMs created by 1.x. You need to create them again.
Requirements
-
A physical Apple Silicon Mac running macOS 15 or newer. It does not work in a macOS VM.
-
Enough disk space. Each VM uses a 64 GB virtual disk by default, and firmware and temporary files take additional space.
-
A network connection. Restoring the system fetches signing tickets online.
-
Adjusted security settings. Boot into macOS Recovery, run these commands in Terminal, then restart:
csrutil enable --without debug csrutil allow-research-guests enableSIP stays enabled, with only the debugging restrictions relaxed. For the reasons and other ways to set this up, see Host Setup.
Get Started
- Download the latest vphone-launchpad (
vphone-launchpad-<version>.zip), unzip it, and open it. - In Host Setup, grant Developer Tools access and install the helper.
- In Core Bundle, click Download and Install. Launchpad downloads and verifies
VPhone.bundle, then allows the VM program inside it to run on your Mac. - In Machines, click New Machine, choose a firmware pairing, and click Create.
Launchpad downloads the firmware, patches it, restores the system, and boots it for the first time. When it finishes, the VM keeps running.
You can also use your own iPhone and cloudOS IPSWs. For verified pairings, see Compatibility.
Install the Package Environment
The VM has no package manager by default. To install one:
- In the menu bar, choose Apps > Install Bootstrap… and select the roothide layout (rootless is deprecated). This installs Irisin in the VM.
- The first time, select
aptandbashin Irisin, press and hold the install button, and choose Bootstrap Install.bashanddebianutilsdepend on each other, so a normal install cannot complete. - After that, use a normal install.
To remove the environment, choose Apps > Uninstall Bootstrap…. The VM restarts after removal.
Hold Option while opening the Apps menu to see two more options:
- Install Bootstrap from File…: Installs from a local Irisin
.deb. - Uninstall Bootstrap Without Restarting…: Removes the environment without restarting the VM.
Command Line
Launchpad manages VMs through the vphone-cli inside VPhone.bundle. You can also use it directly in Terminal:
| Task | Command |
|---|---|
| List VMs | vphone-cli vm list |
| Show VM information | vphone-cli vm info myphone |
| Start a VM | vphone-cli vm launch myphone |
| Stop a VM | vphone-cli vm stop myphone |
| Clone a VM | vphone-cli vm clone myphone copy |
| Export a VM | vphone-cli vm export myphone --out myphone.tzst |
| Import a VM | vphone-cli vm import myphone.tzst --name restored |
VMs are stored in ~/.vphone/ by default. Run vphone-cli <group> --help to see all commands. To create a VM without Launchpad, see Create and Run.
Automation API
Add --api-listen at launch to turn it on:
vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
# The output shows [api] token: …
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
Each launch generates a new token. To use a fixed token, set the VPHONE_API_TOKEN environment variable. Requests without the token and requests from web pages are refused. For the interface reference, see the API documentation.
Troubleshooting
Start with Troubleshooting, which covers cases such as the system refusing the VM program, restore failures, and getting stuck on "Press home to continue". If that does not solve it, open an issue.
Documentation
| Document | Contents |
|---|---|
| Host Setup | SIP and AMFI settings, building from source, environment checks |
| Create and Run | Firmware sources, the creation process, storage and backups |
| Compatibility | Verified firmware pairings |
| Troubleshooting | Common errors and how to fix them |
| Launchpad Command Line | Install and test a local build with vphone-launchpad-cli |
| Research Notes | Patch and implementation details |
Project Structure
vphone-launchpad: A Mac app that downloads and installsVPhone.bundleand sets up the host. Released separately.vphone-cli: Prepares firmware, patches it, restores the system, and manages VMs.vphone-vm: Runs the VM and shows its window.vphoned: The control service inside the VM. The window's features and the API work through it.
| Path | Contents |
|---|---|
VPhoneExecutable/ |
vphone-cli, vphone-vm, firmware patching and restore |
VPhoneKit/ |
Shared host libraries and API client |
VPhoneDaemon/ |
vphoned |
VPhoneGuestComponents/ |
Hooks and helper programs inside the VM |
VPhoneLaunchpad/ |
The Launchpad app and its helper |
To build from source, run xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build. The output is VPhone.bundle.