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.
Requirements
-
A physical Apple Silicon Mac running macOS 15 or newer. It does not work in a macOS VM.
-
Free disk space. Each VM has a 64 GB virtual disk by default, and firmware takes more.
-
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 details, see Host Setup.
Get Started
- Download
vphone-launchpad-<version>-notarized.zipfrom the latest release, unzip it, and open it. Not every release is notarized. If the latest one has no-notarizedfile, pick a notarized version from Downloads. - In Host Setup, grant Developer Tools access and install the helper.
- In Core Bundle, click Download and Install.
- In Machines, click New Machine, choose a firmware pairing, and click Create.
Launchpad downloads the firmware, patches it, restores the system, and boots the VM. To use your own iPhone and cloudOS IPSWs, see Compatibility.
To install a package manager in the VM, see Package Environment.
Command Line
Launchpad drives VMs through the vphone-cli inside VPhone.bundle. You can also run it in Terminal:
vphone-cli vm list
vphone-cli vm launch myphone
vphone-cli vm export myphone --out myphone.tzst
VMs are stored in ~/.vphone/. Run vphone-cli <group> --help to see all commands. To create a VM without Launchpad, see Create and Run.
To turn on the automation API, add --api-listen 127.0.0.1:8765 at launch and use the token it prints. See the API documentation.
Documentation
| Document | Contents |
|---|---|
| Downloads | Notarized Launchpad versions and matching VPhone.bundle versions |
| 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 |
| Package Environment | Installing and removing a package manager in the VM |
| Troubleshooting | Common errors and how to fix them |
| Networking | Network modes, and tunnel for a Mac behind a VPN or proxy |
| Launchpad Command Line | Install and test a local build with vphone-launchpad-cli |
| Contributing | Project structure, building from source, research notes |
If these do not solve your problem, open an issue.