TopGit
GitHub Repo Review

vphone-cli: iPhone on Apple Silicon via Virtualization

Lakr233/vphone-cli
VTopGit review image for Lakr233/vphone-cli
Review by Topgit.dev for Lakr233/vphone-cli, with GitHub repository stats and README context.
Quick verdict

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.

Stars
★ 16.7k
Forks
⑂ 2.0k
Contributors
👥 38
Language
Swift
License
MIT
Topic
Mobile
Updated
Nov 2026
Homepage
—
GitHub

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
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

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

Apple iOS Simulator — ships with Xcode, runs iOS apps without SIP drama, but offers no root access, no kernel research capability, and cannot run jailbreak codeCorellium — cloud-hosted ARM virtual devices with full root, but is a paid SaaS product with no local control and requires uploading your workload to their infrastructureUTM — open-source PC hypervisor that can run ARM64 Linux, but lacks Virtualization.framework integration for iOS and no automated boot-chain patchingcheckra1n + physical device — real iOS hardware with full access, but requires compatible hardware, is tethered, and does not run on Apple Silicon Macs at all

Common questions and error messages

What hardware do I need to run vphone-cli?

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.

Can vphone-cli run on an Intel Mac or inside a VM?

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.

How is vphone-cli different from the official iOS Simulator?

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.

What does the jailbreak variant include vs the regular variant?

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.

How do I fix the killed vphone-cli error on macOS?

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.

Does vphone-cli require disabling SIP?

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

Source & attribution

GitHub repository Lakr233/vphone-cli (MIT License)

GitHub data · last synced Aug 31, 2026Reviewed by Henry
← Back to TopGit

Still deciding about vphone-cli?

One click hands the question to an AI along with this page — see what it says about vphone-cli.

GitHub