vphone-cli: Run Real iOS 26 on Your Mac (No Xcode Required)

What if you could boot a real iPhone running iOS 26—inside a virtual machine on your Mac? Not a simulator. Not an emulator. A genuine virtualized iOS device with full jailbreak capabilities, SSH access, and even app installation via Sileo and TrollStore.

If you've ever wrestled with Xcode's iOS Simulator and screamed into the void because it doesn't support push notifications, CallKit, or real kernel behavior, you're not alone. Apple's simulator is a polished toy for UI testing—and a nightmare for anything involving actual iOS internals. Meanwhile, physical device labs cost thousands, and cloud-based device farms bleed money monthly.

Enter vphone-cli by Lakr233—a command-line tool that leverages Apple's own Virtualization.framework (the same hypervisor powering macOS VMs) to boot real iOS firmware on Apple Silicon Macs. Born from Apple's security-pcc research infrastructure, this tool exposes the hidden capability that's been sitting in macOS Sequoia all along. And the best part? It supports everything from pristine "patchless" iOS to fully jailbroken environments with automated setup.

Ready to turn your Mac into an iOS powerhouse? Let's dissect how vphone-cli works, why it's spreading like wildfire in the reverse-engineering community, and exactly how to get your first virtual iPhone breathing.

What is vphone-cli?

vphone-cli is an open-source command-line interface for booting virtualized iPhone instances using Apple's native Virtualization.framework. Created by developer Lakr233 and built upon Apple's security-pcc (Private Cloud Compute) research VM infrastructure, it represents one of the first public tools to expose iOS virtualization for general development and security research.

The project emerged from Apple's own virtualization research—specifically the PCC (Private Cloud Compute) environment that needed isolated, attestable iOS execution for secure AI processing. While Apple never productized this for developers, the underlying Virtualization.framework gained PV=3 (paravirtualization level 3) support in macOS 15 Sequoia, enabling genuine iOS kernel boot without full hardware emulation.

What makes vphone-cli genuinely exciting is its multi-variant firmware patching system. Rather than forcing a single "hacked" iOS image, it offers four distinct security postures—from a near-stock "Patchless" variant to a fully liberated "Jailbreak" variant with 112 boot chain patches, automated Sileo installation, and TrollStore availability on first boot.

The tool has been tested on Mac16,12 (likely M4 Pro/Max) running macOS 26.3, successfully booting iPhone 17,3 firmware variants across iOS 26.1 through 26.3.1. This isn't theoretical—it's production-ready for researchers who need real iOS behavior without physical device constraints.

Key Features That Make vphone-cli Insane

Four Firmware Variants for Every Security Need

The project's tiered patching architecture is its secret weapon. Each variant applies progressively deeper modifications to the iOS boot chain:

The Jailbreak variant deserves special attention. On first boot, a LaunchDaemon at /cores/vphone_jb_setup.sh automatically finalizes the environment—creating symlinks, installing Sileo (the modern Cydia replacement), configuring apt, and deploying TrollStore for permanent app sideloading. Progress logs to /var/log/vphone_jb_setup.log so you can monitor automation in real-time.

Native Apple Virtualization Framework Integration

Unlike QEMU-based iOS emulation attempts (which crawl at 10% native speed), vphone-cli uses Apple's own hypervisor—the same technology powering UTM and Apple's Virtualization framework documentation. This means:

• Near-native performance for CPU-bound operations
• Automatic memory ballooning and storage optimization
• USB passthrough via pymobiledevice3 for device communication
• VNC console access for graphical interaction

Programmatic VM Control via Unix Socket

The vm/vphone.sock host control socket exposes a binary protocol for automation: screenshots, touch injection, swipe gestures, hardware key simulation, and clipboard operations. Every action returns a compact grayscale screenshot, enabling AI-driven end-to-end testing workflows. The companion vphone-mcp project wraps this into an MCP (Model Context Protocol) server for Claude Code integration.

Sparse Disk Backup & Instant Environment Switching

Research projects often need multiple iOS versions or configurations. vphone-cli's make vm_backup uses rsync --sparse for efficient disk image deduplication, storing environments in vm.backups/. Switch between a "clean iOS 26.1" and "jailbroken iOS 26.3" in seconds with make vm_switch.

Real-World Use Cases Where vphone-cli Dominates

1. iOS Security Research Without Physical Device Risk

Kernel exploit development traditionally requires sacrificial iPhones—devices you don't mind bricking. With vphone-cli's Development or Jailbreak variants, researchers can:

• Patch the kernel in real-time via TXM (Trusted Execution Monitor) bypasses
• Attach debuggers through entitlement-injected binaries
• Snapshot VM state before dangerous experiments
• Restore to known-good state in minutes, not hours

2. Automated App Testing at the System Level

XCTest and XCUITest can't touch system dialogs, VPN configurations, or MDM enrollment flows. vphone-cli's automation socket enables true black-box testing:

# Conceptual: AI agent using vphone-mcp to navigate iOS setup
# The socket returns screenshots after every action for visual verification

Teams can validate entire user onboarding flows, including Apple ID sign-in, iCloud backup restoration, and carrier activation—impossible in Simulator.

3. Legacy iOS Compatibility Verification

With IPHONE_SOURCE and CLOUDOS_SOURCE environment variables, you can pin specific IPSW versions. Maintain a library of virtual devices running iOS 26.1, 26.2, 26.3 for regression testing. The patchless variant ensures you're testing against minimally-modified firmware.

4. Continuous Integration for Mobile Security Tools

Tools like pymobiledevice3, ipsw, and go-ios need real iOS targets. vphone-cli enables headless CI pipelines:

# GitHub Actions conceptual workflow
make vm_new CPU=4 MEMORY=4096 DISK_SIZE=32 NONE_INTERACTIVE=1
make setup_machine SUDO_PASSWORD=${{ secrets.MAC_PASSWORD }}
make boot &
# Run test suite against SSH-forwarded ports

Step-by-Step Installation & Setup Guide

Prerequisites: Prepare Your Host Mac

Critical requirement: macOS 15+ (Sequoia) with PV=3 virtualization support. Only Apple Silicon Macs are supported—Intel Macs lack the required Virtualization.framework features.

You must modify SIP (System Integrity Protection) for private entitlements. This is non-negotiable. Choose your security posture:

Option 1: Fully disable SIP + AMFI (most permissive, required for Patchless variant):

# Boot into Recovery (long-press power button), open Terminal:
csrutil disable
csrutil allow-research-guests enable

# After restarting to macOS:
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
# Restart once more

Option 2: Minimal SIP modification with amfidont/amfree:

# In Recovery:
csrutil enable --without debug
csrutil allow-research-guests enable

# After restart, install AMFI bypass tools:
# Using amfidont:
xcrun python3 -m pip install amfidont
sudo amfidont --path /path/to/vphone-cli

# OR using amfree:
brew install retX0/tap/amfree
sudo amfree --path /path/to/vphone-cli

# Repo helper for automated allowlist:
make amfidont_allow_vphone

Warning: The Patchless variant specifically requires Option 1, or amfidont with -S flag: sudo amfidont -S --path [PATH].

Install Dependencies

# 1. Homebrew dependencies (critical tools for IPSW manipulation)
brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd

# 2. Clone with submodules (contains vendored Swift deps and toolchain sources)
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
cd vphone-cli

The scripts/fw_prepare.sh script prefers aria2c for multi-connection IPSW downloads—critical for Apple's multi-gigabyte firmware files.

Automated Setup (Recommended)

# Full automation through first boot—including restore, ramdisk, and CFW installation
make setup_machine

# Non-interactive mode for CI/automation:
make setup_machine NONE_INTERACTIVE=1 SUDO_PASSWORD=yourpassword

# Variant selection:
make setup_machine LESS=1    # Patchless: minimal patches, near-stock iOS
make setup_machine DEV=1     # Development: +TXM debug bypasses
make setup_machine JB=1      # Jailbreak: full bypass with Sileo/TrollStore

REAL Code Examples from vphone-cli

Example 1: VM Creation with Custom Configuration

# Create VM with enterprise-grade resources
make vm_new CPU=16 MEMORY=16384 DISK_SIZE=128

# Boot automatically reads from vm/config.plist
make boot

The config.plist follows security-pcc's VMBundle.Config format, ensuring compatibility with Apple's official virtualization tools. The manifest stores CPU count, memory allocation, screen configuration, ROM paths, and storage settings—everything needed for reproducible environments.

Key insight: The CPU=16 parameter allocates 16 virtual cores to the iOS guest. iOS is surprisingly thread-hungry during setup and app installation; under-provisioning causes timeouts in make setup_machine.

Example 2: Two-Terminal Restore Process

# TERMINAL 1 — Keep running throughout restore
make boot_dfu
# This boots the VM in Device Firmware Update mode
# The Virtualization.framework presents a virtual USB device to the host

# TERMINAL 2 — Flashing operations
make restore_get_shsh    # Fetch SHSH blob from Apple's servers (or TSS cache)
make restore             # Full restore via pymobiledevice3 backend
# OR for air-gapped environments:
make restore_offline     # Decrypts AEA images locally, uses cached .shsh

The SHSH blob (Signature HaSH) is Apple's cryptographic ticket for firmware installation. vphone-cli caches this to enable offline restores—a lifesaver for reproducible research environments. The pymobiledevice3 backend handles the complex IPSW parsing, partition table creation, and filesystem extraction that would require hundreds of lines of manual img4tool commands.

Example 3: Custom Firmware Installation via SSH Ramdisk

# TERMINAL 1 — Reboot to DFU for ramdisk
make boot_dfu

# TERMINAL 2 — Build and deploy signed SSH ramdisk
sudo make ramdisk_build   # Creates cryptographically signed ramdisk
make ramdisk_send         # Transfers via virtual USB

# TERMINAL 3 — USB multiplex tunnel (keep running)
python3 -m pymobiledevice3 usbmux forward 2222 22

# TERMINAL 2 — Install CFW through SSH tunnel
make cfw_install          # Regular variant
# OR:
make cfw_install_jb       # Jailbreak: triggers automated Sileo/TrollStore setup

This three-terminal dance is the core magic of vphone-cli. The ramdisk is a minimal iOS environment with SSH server, injected into the boot process before the main filesystem mounts. This allows live modification of the root partition—patching kernels, injecting entitlements, and installing package managers.

The usbmux forward command creates a TCP-to-USB proxy, because iOS devices (even virtual ones) communicate over Apple's proprietary usbmux protocol, not raw TCP. pymobiledevice3 bridges this gap, exposing SSH on localhost:2222.

Example 4: First Boot Shell Initialization (Regular/Dev Variants)

# After cfw_install completes, first boot shows bash-4.4# prompt
# Initialize environment for meaningful shell access:

export PATH='/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games:/iosbinpack64/usr/local/sbin:/iosbinpack64/usr/local/bin:/iosbinpack64/usr/sbin:/iosbinpack64/usr/bin:/iosbinpack64/sbin:/iosbinpack64/bin'

# Create runtime directories expected by dropbear SSH server
mkdir -p /var/dropbear
cp /iosbinpack64/etc/profile /var/profile
cp /iosbinpack64/etc/motd /var/motd

# CRITICAL: Generate SSH host keys
dropbearkey -t rsa -f /var/dropbear/dropbear_rsa_host_key
dropbearkey -t ecdsa -f /var/dropbear/dropbear_ecdsa_host_key

shutdown -h now  # Clean shutdown to persist keys

Why this matters: The /iosbinpack64 directory contains a precompiled iOS binary pack—standard Unix utilities cross-compiled for arm64 iOS. Without dropbearkey generation, the SSH server accepts connections then immediately drops them, producing the maddening "connection closed" symptom that stumps new users.

Example 5: Subsequent Boot Port Forwarding

# Start VM
make boot

# In separate terminal, forward all services
python3 -m pymobiledevice3 usbmux forward 2222 22222   # dropbear SSH (regular/dev)
python3 -m pymobiledevice3 usbmux forward 2222 22      # openssh-server (jailbreak)
python3 -m pymobiledevice3 usbmux forward 5901 5901    # VNC screen sharing
python3 -m pymobiledevice3 usbmux forward 5910 5910    # RPC research interface

# Connect via:
ssh -p 2222 root@127.0.0.1        # Regular/Dev (password: alpine)
ssh -p 2222 mobile@127.0.0.1      # Jailbreak (password: alpine)
open vnc://127.0.0.1:5901         # Screen control
rpcclient -p 5910 127.0.0.1       # [doronz88/rpc-project](https://github.com/doronz88/rpc-project)

The port number distinction (2222 vs 22) reflects iOS's user model: regular/dev variants run SSH as root directly, while jailbreak variants create a proper mobile user (UID 501) matching physical iPhone behavior.

Advanced Usage & Best Practices

Sparse Backup Strategy for Multiple Environments

# Save pristine state before experiments
make vm_backup NAME=26.1-baseline

# Create experimental branch
make vm_new CPU=8 MEMORY=8192
# ... apply patches, test exploits ...
make vm_backup NAME=26.3-exploit-dev

# Instant rollback
make vm_list                    # Show all: 26.1-baseline, 26.3-exploit-dev...
make vm_switch NAME=26.1-baseline

The rsync --sparse optimization is crucial: iOS disk images are mostly empty, and sparse copying preserves this efficiency. A 128GB VM might consume only 3-4GB actual storage.

Automation Socket for AI-Driven Testing

The vm/vphone.sock exposes binary commands for:

• screenshot — Returns 128x128 grayscale for rapid AI vision processing
• touch x y — Inject tap at screen coordinates
• swipe x1 y1 x2 y2 duration — Gesture simulation
• key home / key power / key volup — Hardware button simulation
• clipboard get / clipboard set — Cross-VM copy-paste

Pair with vphone-mcp for natural language control: "Open Settings, navigate to Privacy, screenshot the current page."

Region Selection Trap

Critical: During iOS setup, never select Japan or EU regions. These trigger regulatory checks (sideloading disclosures, camera shutter requirements) that fail in virtualized environments, blocking system app downloads permanently. Choose United States or other non-regulated regions.

Comparison with Alternatives

vphone-cli's unique position: It's the only free, locally-hosted solution with automated jailbreak deployment and AI-ready automation. Corellium offers more mature enterprise features but costs thousands monthly. Physical devices require constant manual intervention.

FAQ: What Developers Ask About vphone-cli

Q: Why does ./vphone-cli get killed immediately?

AMFI (Apple Mobile File Integrity) is blocking the unsigned binary. You must either disable AMFI via nvram boot-args or use amfidont/amfree with proper path allowlisting. Run make amfidont_allow_vphone for automated setup.

Q: "Virtualization is not available on this hardware"—but I have an M3 Mac!

You're likely running inside a VM already (nested virtualization). Check make boot_host_preflight—if it shows Apple Virtual Machine 1 with kern.hv_vmm_present=1, you need bare metal. This affects Parallels, UTM, and cloud Mac instances.

Q: Can I update to newer iOS versions?

Yes! Override firmware sources and re-patch:

export IPHONE_SOURCE=/path/to/new.ipsw
export CLOUDOS_SOURCE=/path/to/new.ipsw
make fw_prepare && make fw_patch

Binary analysis-based patches (not static offsets) make this resilient across versions.

Q: How do I simulate the Home button?

Connect via VNC (vnc://127.0.0.1:5901) and right-click anywhere (two-finger click on trackpad). This injects the virtual Home button press.

Q: Can I install .tipa files?

Yes—both .ipa and .tipa formats are supported in the install menu. Drag-drop or file picker both work.

Q: Is this legal for App Store development?

The tool itself operates within Apple's research frameworks, but jailbroken variants violate iOS Terms of Service. Use Patchless/Regular variants for legitimate development; reserve Jailbreak for security research only.

Q: Why won't system apps download?

You selected Japan or EU during setup. These regions enforce additional checks that fail in VMs. Restore and select United States.

Conclusion: The Future of iOS Development is Virtual

vphone-cli isn't just a clever hack—it's a paradigm shift. For the first time, individual developers can spin up real iOS environments with the same ease as Docker containers, complete with automated jailbreak deployment, SSH access, and AI-controllable automation sockets.

The four-tier patching system (Patchless through Jailbreak) means you choose your security posture per-project. Need pristine iOS for App Store validation? Patchless. Need kernel debugging for exploit research? Development. Want Sileo and TrollStore ready in minutes? Jailbreak variant's automated setup has you covered.

Yes, the SIP modifications and AMFI bypasses create friction. Yes, you need macOS 15+ on Apple Silicon. But compare this to maintaining a drawer of physical iPhones, each locked to specific iOS versions, each requiring manual restore when experiments go wrong.

The virtualization future Apple hinted at with security-pcc is here, and Lakr233's vphone-cli is your open-source gateway. Whether you're building automated testing pipelines, researching iOS internals, or just tired of Simulator's limitations, this tool demands your attention.

⭐ Star vphone-cli on GitHub — and join the growing community of developers who've stopped fighting their tools and started virtualizing them.

Boot real iOS. Automate everything. Never buy another test device.