Skip to content
Get packs

Guide · Open source

How to use vphone-cli: run a virtual iPhone on your Mac

Updated · written with AI from the project's own documentation and checked against our catalogue data

vphone-cli is an open-source (MIT licensed, written in Swift) project that runs iOS inside a virtual machine on an Apple Silicon Mac, using Apple's Virtualization.framework. The README says it is meant for security research, reverse engineering, and debugging. This guide explains what you need before you start, how to set it up with Launchpad, and how to run and manage virtual iPhones from the command line.

vphone-cliLakr233/vphone-cli · ★ 16.4k · MIT

Quick start

  1. 1Confirm your Mac qualifies. Make sure you have a physical Apple Silicon Mac running macOS 15 or newer, with enough free disk space for a 64 GB VM plus firmware.
  2. 2Adjust SIP in macOS Recovery. Boot into Recovery, run the two csrutil commands in Terminal, and restart. SIP stays enabled with only debugging restrictions relaxed.
  3. 3Download and open Launchpad. Get the notarized vphone-launchpad zip from the latest release, unzip it, and open it.
  4. 4Install the helper and Core Bundle. In Host Setup, grant Developer Tools access and install the helper. In Core Bundle, click Download and Install.
  5. 5Create a machine. In Machines, click New Machine, choose a firmware pairing, and click Create. Launchpad downloads, patches, restores and boots the VM.
  6. 6Manage VMs from Terminal. Use vphone-cli vm list, vm launch and vm export to manage your virtual iPhones.

Check the requirements before you install

vphone-cli only works on a physical Apple Silicon Mac running macOS 15 or newer. The README says it does not work inside a macOS virtual machine.

You also need free disk space. Each VM has a 64 GB virtual disk by default, and the firmware takes more. Setup needs a network connection because restoring the system fetches signing tickets online.

  • Physical Apple Silicon Mac running macOS 15 or newer
  • Free disk space: 64 GB per VM by default, plus firmware
  • A network connection
  • Adjusted SIP settings (see the next section)

Change the security settings in macOS Recovery

Setup requires changing System Integrity Protection (SIP) options. Boot into macOS Recovery, open Terminal, run the two commands below, then restart. The README says SIP stays enabled and only the debugging restrictions are relaxed.

Only do this if you are comfortable lowering these host protections. The README links to a Host Setup guide with more detail.

csrutil enable --without debug csrutil allow-research-guests enable

Install and set up with Launchpad

Download the notarized Launchpad release from the latest release page, unzip it, and open it. The README notes that not every release is notarized. If the latest one has no -notarized file, pick a notarized version from the Downloads page in the docs.

Launchpad guides the rest of setup. Grant Developer Tools access and install the helper in Host Setup, click Download and Install in Core Bundle, then click New Machine in Machines, 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 the Compatibility guide in the docs.

  • Download vphone-launchpad-<version>-notarized.zip from the latest release and unzip it
  • Open 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
git clone https://github.com/Lakr233/vphone-cli

Use the command line

Launchpad drives VMs through the vphone-cli inside VPhone.bundle, and you can also run it directly in Terminal. VMs are stored in ~/.vphone/. Run vphone-cli <group> --help to see all commands.

To turn on the optional automation API, add --api-listen 127.0.0.1:8765 at launch and use the token it prints. The API documentation is in the research folder of the repository.

  • vm list shows your VMs
  • vm launch starts one by name
  • vm export saves a VM to a file
  • vm config switches boot ROMs; vm info shows which ROMs a VM uses
vphone-cli vm list vphone-cli vm launch myphone vphone-cli vm export myphone --out myphone.tzst

Understand the boot ROMs and the pre-patched system

New VMs start from two open-source boot ROMs, OpenAVB and OpenSEP, instead of Apple's closed ones. The README says that with both, nothing Apple wrote runs before iBoot and SEPOS. VMs created by earlier versions keep Apple's ROMs, and you can switch a VM between them from its next start without a restore.

Restoring a VM that boots OpenAVB needs VPhone.bundle 2.10.1 or newer. The README also states that the system comes pre-patched, so a stock, unmodified iOS install is not what you get.

vphone-cli vm config myphone --rom openavb --seprom opensep vphone-cli vm config myphone --rom apple --seprom apple

Troubleshoot and get help

The project's docs include a Troubleshooting guide for common errors, a Networking guide covering network modes and the tunnel option for a Mac behind a VPN or proxy, and a Snapshots guide for saving a stopped VM's disk state. If these do not solve your problem, the README points to the project's issue tracker.

  • Troubleshooting: common errors and fixes
  • Networking: network modes and tunnel for VPN or proxy setups
  • Snapshots: save and revert a stopped VM's disk
  • Issues: open a report on the GitHub issues page

What people use it for

  • Security researchers studying iOS behavior in a controlled environment
  • Reverse engineers who want a virtual iPhone on their own Mac
  • Developers debugging iOS software without a physical device
  • Taking screenshots and screen recordings of the virtual iPhone screen
  • Exporting, importing and cloning VMs for repeatable test setups

Frequently asked questions

Is vphone-cli free?

vphone-cli is released under the MIT licence, according to the repository. The README also warns that the project has never issued or authorised any cryptocurrency or token, and does not accept crypto payments or donations.

What do I need to run vphone-cli?

You need a physical Apple Silicon Mac running macOS 15 or newer, free disk space (64 GB per VM by default, plus firmware), a network connection, and adjusted SIP settings changed in macOS Recovery. It does not work in a macOS virtual machine.

Can I run vphone-cli in a macOS VM?

No. The README says it does not work in a macOS VM and requires a physical Apple Silicon Mac.

Do I need Xcode, Python or Homebrew?

The README says vphone-cli needs no Xcode, Python, or Homebrew at runtime.

Is the virtual iPhone a stock iOS install?

No. The README says the system comes pre-patched, so users who need an unmodified stock iOS install should look elsewhere.

Why does it ask me to change SIP settings?

Setup requires relaxing the debugging restrictions in System Integrity Protection through macOS Recovery. The README says SIP stays enabled and only those debugging restrictions are relaxed. Users who cannot make that change should not use this project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

vphone-cli suits security researchers, reverse engineers and developers who have a physical Apple Silicon Mac on macOS 15 or newer and are willing to relax some debugging protections in macOS Recovery. If you need a stock iOS install, do not have a physical Apple Silicon Mac, or cannot change SIP options, pick a different approach, such as a physical iPhone.

Install options & downloads