vphone-cli: iPhone on Apple Silicon via Virtualization
vphone-cli boots a real iOS system inside a macOS VM on Apple Silicon using Apple's Virtualization.framework. Five firmware variants go from a 4-patch `less` profile to a 141-patch `exp` superset with anti-VM-detection research patches; the `jb` variant auto-installs Sileo and TrollStore on first boot. Worth the setup friction if you need bare-metal iOS on your Mac — skip it if you just want app UI testing and the official Simulator covers that fine.
Booting a real iPhone OS in a VM on Apple Silicon
vphone-cli virtual iPhone is a Swift CLI that builds and runs a real iOS VM on Apple Silicon using Apple's Virtualization.framework. It automates the full chain: IPSW download, boot-chain patching, DFU restore, and CFW installation — letting you spawn a virtual iPhone with a single command.
Core capabilities of vphone-cli
- ✓One-command VM creation: `vphone-cli vm create myphone -V jb` runs the entire pipeline from IPSW download through first boot
- ✓Five firmware variants: `less` (4 patches), `regular` (42 patches), `dev` (53 patches), `jb` (113 patches), and `exp` (141 patches with anti-VM-detection research patches)
- ✓CLI-driven or manual workflow: use the all-in-one `vm create` or drive each step (`fw prepare`, `fw patch`, `restore`, `cfw install`) individually
- ✓SSH and VNC access: jailbreak VMs expose port 22222 for SSH as `mobile`/`alpine`, regular VMs as `root`/`alpine`; VNC on port 5901
- ✓Host control socket for automation: exposes touch, swipes, hardware keys, clipboard, and screenshots via `<bundle>/vphone.sock`
- ✓Python runtime auto-provisioned: `~/.vphone/venv/` created on first run with all needed dependencies
- ✓Configurable storage layout: `$VPHONE_ROOT`, `$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR` override defaults for VMs, cache, and venv locations
- ✓MCP server available: vphone-mcp wraps the control socket for AI-driven E2E testing workflows
Installing vphone-cli and its dependencies
Install vphone-cli via Homebrew: `brew install zqxwce/tap/vphone-cli`. The tap formula handles the binary. After installing, you still need to relax host security — see the SIP/AMFI Relaxation section. On first run, vphone-cli auto-creates the Python venv under `~/.vphone/venv/` with all required dependencies.
Creating and launching your first virtual iPhone
Create and launch a virtual iPhone with one command: `vphone-cli vm create myphone -V jb`. This downloads the IPSW, patches the boot chain, performs a DFU restore, installs CFW, and boots into iOS. Once created, launch with `vphone-cli vm launch myphone`. Access the VM via SSH at `ssh -p 22222 mobile@<vm-ip>` (password `alpine`) for jailbreak VMs, or `ssh -p 22222 root@<vm-ip>` for regular ones. Connect via VNC at `vnc://<vm-ip>:5901`.
Strengths
- ✓One command (`vphone-cli vm create`) automates the entire pipeline: downloads IPSWs, patches the boot chain, runs a DFU restore, installs CFW, and boots the VM — no manual steps required after that.
- ✓Five firmware variants let you dial in exactly how much you want to disable — from the patchless `less` variant (keeps iOS mitigations) to the 141-patch `exp` variant with anti-VM-detection research patches.
- ✓VM lifecycle is first-class: fast APFS clones with fresh device identity, zstd export that skips restore/staging files, and a complete set of rename/delete/list operations — all scriptable with `--json`.
- ✓A host control socket (`vphone.sock`) exposes screenshot, touch, swipe, key press, and clipboard — the README specifically calls out AI-driven E2E testing as a use case, with a dedicated MCP server (vphone-mcp) wrapping it.
- ✓Data lives in `~/.vphone/` outside the app bundle, and cache directories for IPSWs, APFS seal-volume artifacts, and `.deb` packages are all reusable across VMs.
Hardware requirements and known constraints
- △Apple Silicon and macOS 15+ (Sequoia) are hard requirements — Intel Macs and older macOS versions are not supported, and the tool explicitly refuses to boot if it detects the host is itself a VM (nested PV=3 virtualization is unsupported).
- △SIP and AMFI must be relaxed before the tool will run, which means either disabling System Integrity Protection entirely and setting an nvram boot-arg, or compiling a custom allowlist binary — neither is a one-click step and both carry security implications.
- △A known bug in the Homebrew-released `ldid-procursus` (up to `2.1.5-procursus7`) causes unbounded memory growth and hangs when re-signing certain Apple system binaries that contain integer values of exactly `0` in their entitlements plist; the README documents the workaround as rebuilding from `--HEAD`.
- △iOS 18 base images trigger `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` crashes on launch unless you force the `exc-guard` flag (`--force-exc-guard`) when patching and re-restoring — an extra step not required for earlier iOS versions.
- △Selecting Japan or the EU region during iOS setup causes system apps to refuse installation due to regulatory checks the VM cannot satisfy; the README advises picking United States instead.
How vphone-cli compares to other iOS-on-Mac options
Common questions and error messages
You need an Apple Silicon Mac running macOS 15 Sequoia or later, with Xcode and the iOS SDK installed. The tool uses Apple's Virtualization.framework which only runs on real Apple Silicon hardware — no Intel, no nested VMs.
No. The underlying Virtualization.framework does not expose PV=3 guest support inside nested virtual machines, and the framework itself does not exist on Intel Macs at all. You need bare-metal Apple Silicon.
The Simulator runs a recompiled version of iOS libraries on the Mac's native architecture — it's fast and integrated with Xcode, but it is not a real kernel, has no root access, and cannot run jailbreak code. vphone-cli boots an actual iOS system via Virtualization.framework.
The `regular` variant applies 42 boot-chain patches and 10 CFW phases. The `jb` variant goes to 113 patches and 14 phases, adding a full jailbreak that auto-installs Sileo and TrollStore on first boot. The `exp` variant extends further with 141 patches and 18 phases including anti-VM-detection research patches.
The `zsh: killed` error means AMFI or debug restrictions are blocking the binary. Either set the `amfi_get_out_of_my_way=1` boot-arg after disabling SIP with `csrutil disable` in Recovery, or keep SIP on and run `vphone-amfidont` to allowlist the binary.
Partially. You must enable `csrutil allow-research-guests enable` in Recovery regardless. Full SIP disable is only required if you want the most permissive `amfi_get_out_of_my_way=1` boot-arg. Keeping SIP on with debug-relaxed mode and using `vphone-amfidont` is the alternative.
Best use cases
- •Researching iOS kernel internals, AMFI, and SSV without a physical device
- •Running and iterating on jailbreak tweaks locally before testing on real hardware
- •Automating iOS UI testing via the host control socket and screenshots
- •Building CFW workflows that need DFU restore and SHSH blob fetching
- •Running iOS in a reproducible, disposable environment tied to a specific iOS version
- •Testing system-level iOS behavior (not just app-layer) on a real kernel
Who should try it — and who should skip
Try vphone-cli if you are an iOS security researcher, a jailbreak tweak developer, or an automation engineer who needs a real iOS kernel and system-level APIs without a physical device. Skip it if you only need to test app UI — the official Simulator is faster and simpler. Skip it if you lack Apple Silicon hardware or are unwilling to handle the SIP/AMFI host setup. Developers who need reproducible CI/CD iOS environments will find the most value in the scripted pipeline.
Related repositories
Still deciding about vphone-cli?
One click hands the question to an AI along with this page — see what it says about vphone-cli.
