Who vphone-cli is for#
iOS security researchers testing jailbreak tooling
The `jb` and `exp` variants boot a fully jailbroken iPhone VM with Sileo and TrollStore pre-installed. Researchers can install IPAs, run unsigned binaries, and test exploit mitigations without risking a physical device or navigating Corellium's approval and enterprise pricing process.
Skip if:
Skip if your research requires specific hardware peripherals such as NFC, Bluetooth radios, or cellular. The VM does not expose hardware radios or a GPU to the guest, so workloads that depend on them will not behave correctly.
Mobile QA engineers running offline iOS test suites
vphone-cli's host control socket lets any test harness send taps, swipes, and keyboard input to the VM and receive screenshots after each action. Combined with the vphone-mcp server, it fits AI-driven end-to-end test pipelines without a physical device bench or a cloud device farm subscription.
Skip if:
Skip if your QA pipeline targets physical device farms for app store certification or requires hardware-level performance profiling. vphone-cli is a research VM, not a certified test environment, and its performance characteristics differ from bare-metal iPhone hardware.
Developers building and debugging iOS apps locally
The `dev` variant exposes TXM entitlement and debug bypass, letting developers install and debug custom apps without pairing a physical device. Clone a clean VM state before each test run and restore it afterward, giving a repeatable baseline that physical devices cannot easily provide.
Skip if:
Skip if you primarily use the Xcode Simulator and your app does not exercise code paths that differ between Simulator and real iOS. vphone-cli adds significant setup overhead (SIP relaxation, firmware patching) that the Simulator avoids entirely.
CI/CD engineers adding headless iOS runs to pipelines
Because vphone-cli is a pure CLI with no GUI dependency, it can run in headless macOS CI environments, including GitHub Actions with Apple Silicon macOS runners. Create a VM once, export the snapshot, import it at the start of each pipeline run for a clean state, and drive it via the control socket.
Skip if:
Skip if your CI fleet does not include bare-metal Apple Silicon macOS runners. vphone-cli has no Intel or Linux support, so it cannot run on x86 or ARM Linux CI infrastructure, which covers the majority of existing CI setups.
The problem it solves#
iOS development and security research require access to real device behavior, which has historically meant either managing a fleet of physical iPhones or paying per-minute cloud fees to commercial device farms. BrowserStack and Sauce Labs charge subscription rates that compound quickly for CI/CD pipelines or research workflows that run dozens of test sessions a day. Corellium's iPhone virtualization is restricted to approved researchers and enterprise customers at enterprise pricing.
Physical devices create their own pain: they need provisioning, cable management, and a macOS host running Xcode for automation. Scaling beyond a handful of devices becomes an operations problem rather than a development problem. Teams end up constrained by the number of physical phones they own, with no fast way to snapshot or clone a device state for branched testing scenarios.
How it solves it#
One-command VM creation pipeline
A single `vphone-cli vm create` command handles the full setup sequence: IPSW download, boot chain patching, DFU restore, custom firmware install, and first boot. Each step can also be run individually for scripted or partial workflows that need to re-run one stage without repeating the whole pipeline.
Five firmware variants with tunable security bypass
Five patch variants control how much of iOS's security model is bypassed, from `less` (4 patches, mitigations kept) to `exp` (141 patches, jailbreak superset plus anti-VM-detection research patches). The `jb` variant applies 113 patches and auto-installs Sileo and TrollStore on first boot.
SSH and VNC access to the running VM
Jailbroken VMs expose an SSH server on port 22222 (password `alpine`). Regular and dev variants use root SSH on the same port. A VNC server runs on port 5901 for graphical access. Both are reachable at the VM's IP address with no extra tooling or port forwarding configuration.
Host control socket for programmatic automation
vphone-cli exposes a Unix domain socket (`<bundle>/vphone.sock`) for programmatic control of touch, swipe, hardware keys, clipboard, and screenshots. Each action returns an inline screenshot. The vphone-mcp MCP server wraps this socket so any MCP-compatible AI agent can drive the virtual iPhone.
Fast APFS clone and portable export/import
VMs clone instantly via APFS copy-on-write (`vphone-cli vm clone`), creating a fresh device identity without duplicating data on disk. Export produces a zstd-compressed archive by default, with xz -9 available for maximum compression. Import restores from any exported archive, optionally with a new name.
Per-VM configurable CPU, memory, and disk
Each VM bundle stores its own resource settings. `vphone-cli vm config` sets CPU count, memory in MB, and disk allocation independently per VM. You can run a low-resource VM for quick smoke tests alongside a high-resource VM for performance profiling on the same host machine.
Strengths and trade-offs#
Strengths
- MIT licensed with zero cloud dependencyThe entire tool runs locally under the MIT license. There is no license server, no cloud component, and no per-minute billing. Running 100 VM sessions costs the same as running one. Compared to BrowserStack or Sauce Labs, which meter usage by the minute, vphone-cli's operational cost is fixed at zero after hardware.
- Real iOS firmware, not a simulated environmentvphone-cli boots actual iPhone firmware images via Apple's Virtualization.framework, not the Xcode Simulator. The VM passes the same OS integrity checks a real device would, making it useful for testing code paths that the Simulator skips, including jailbreak detection bypasses and low-level system behavior.
- AI-driven test automation via MCP serverThe vphone-mcp project wraps vphone-cli's host control socket as an MCP server, letting any MCP-compatible AI agent drive the virtual iPhone: tap coordinates, read clipboard, send hardware key events, and capture screenshots after each action. This makes vphone-cli a headless iOS device for AI test harnesses.
- Full VM lifecycle management in one CLIvphone-cli handles create, clone, export, import, rename, delete, and config in one tool with no separate GUI or management layer required. VM state is portable: export a clean snapshot before a destructive test run, then restore it afterward with a single import command.
Trade-offs
- -Requires Apple Silicon and macOS 15 Sequoiavphone-cli only runs on Apple Silicon Macs with macOS 15 (Sequoia) or later. Intel Macs, Linux, and Windows are not supported. This restricts use to teams whose CI or development machines are M-series Macs, which rules out most existing cloud CI infrastructure.
- -SIP and AMFI must be relaxed on the hostRunning vphone-cli requires relaxing system integrity settings on the host Mac. Option A disables SIP entirely (most permissive). Option B uses the bundled `amfidont` tool to allowlist only the vphone-cli binary while keeping AMFI enabled system-wide. Either path modifies host-level security settings in a way that affects the whole machine.
- -Nested virtualization is not supportedvphone-cli cannot run inside another VM. If the host Mac is itself a virtual machine, the Virtualization.framework private entitlement (PV=3) required for guest boot is unavailable. Use on bare-metal macOS 15+ only. This rules out running vphone-cli on most cloud macOS instances that are themselves virtualized.
- -Dependency complexity and a known ldid build bugInstalling from source requires Xcode, iOS SDK, and 13 Homebrew dependencies. A known bug in ldid-procursus up to version 2.1.5-procursus7 causes the `cfw install` step to hang on system binaries with integer-0 entitlements. The workaround is building ldid from HEAD (`brew install --HEAD ldid-procursus`), which is not the default Homebrew stable version.
vphone-cli vs alternatives#
vphone-cli vs BrowserStack
BrowserStack provides remote access to a real iOS device cloud. It is a fully managed service with no self-hosting option. vphone-cli boots a local iPhone VM on your own Mac, eliminating per-minute billing at the cost of requiring Apple Silicon hardware and macOS 15 Sequoia.
| Feature | vphone-cli | BrowserStack |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (required) | No |
| iOS environment | Virtual iPhone, local | Remote real device cloud |
| Pricing | Free (hardware cost only) | Subscription, metered per minute |
| Offline use | Yes | No |
vphone-cli is the better choice when you need offline access, cost control on high-volume test runs, or a jailbroken iOS environment for security research. BrowserStack is the better choice when your team lacks Apple Silicon Macs, when you need testing on specific certified physical device models, or when a real-device environment is required for compliance.
vphone-cli vs Sauce Labs
Sauce Labs is a cloud-based continuous testing platform with real device options for iOS. Like BrowserStack, it is fully managed with no self-hosting path. vphone-cli differs in being locally hosted and jailbreak-capable, which Sauce Labs does not offer.
| Feature | vphone-cli | Sauce Labs |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (required) | No |
| Jailbreak support | Yes (jb and exp variants) | No |
| Pricing | Free (hardware cost only) | Enterprise subscription |
| CI/CD use | CLI-native, headless | Web dashboard plus REST API |
vphone-cli fits teams running CI on Apple Silicon macOS runners who want to eliminate per-test charges. Sauce Labs is the better fit when your CI infrastructure is Linux or Windows and cannot run macOS.
vphone-cli vs Corellium
Corellium is the closest commercial product to vphone-cli: it virtualizes real iOS devices in the cloud using a similar approach to Apple's virtualization layer. Access is restricted to approved organizations at enterprise pricing, with no open source path.
| Feature | vphone-cli | Corellium |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (your Mac) | No (managed cloud) |
| Access model | Open source, anyone installs | Application and approval required |
| Jailbreak variants | 5 (less through exp) | Available via research access |
| Pricing | Free | Enterprise (undisclosed) |
vphone-cli is the clear choice for individuals and teams who own Apple Silicon Macs and want Corellium-like virtualization without an approval process or enterprise pricing. Corellium remains relevant when you need cloud-hosted virtual devices accessible to a distributed team without requiring everyone to own an Apple Silicon Mac.
Install and self-host#
Install vphone-cli via a Homebrew tap after installing the required dependencies.
```bash
brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
brew install zqxwce/tap/vphone-cli
```What it's built on#
- Languages
- Objective-CPythonSwift
FAQ#
Does vphone-cli run on Intel Macs or Linux?
No. vphone-cli requires Apple Silicon (M-series) and macOS 15 Sequoia or later. The Virtualization.framework private entitlement (PV=3) that vphone-cli relies on is only available on Apple Silicon hardware. Intel Macs, Linux, and Windows are not supported in any configuration.
Is it safe to relax SIP and AMFI on my development Mac?
Two options are available with different security trade-offs. Option A disables SIP entirely, which is the most permissive configuration. Option B keeps AMFI enabled system-wide and uses the bundled amfidont tool to allowlist only the vphone-cli binary, reducing the blast radius. Neither option is risk-free; using a dedicated machine or a machine you accept as having a reduced security posture is the safest approach.
What is the difference between the jb and exp firmware variants?
The jb variant applies 113 boot chain patches and 14 CFW phases, auto-installing Sileo and TrollStore on first boot. The exp variant adds 28 more patches on top of jb (141 total, 18 CFW phases), including anti-VM-detection research patches. Use exp when your research requires the VM to evade anti-jailbreak or anti-VM detection checks. Use jb for standard jailbroken environments without the extra bypass overhead.
Can vphone-cli run multiple VMs simultaneously?
Yes. Each VM is an independent bundle under ~/.vphone/VMs/ and can be launched with a separate vphone-cli vm launch call. The practical limit is your Mac's available RAM and CPU. vphone-cli vm config sets the per-VM resource allocation, so you can tune each VM to fit your available headroom.
Is there an MCP integration for AI-driven iOS testing?
Yes. The vphone-mcp project (available at github.com/pluginslab/vphone-mcp) wraps vphone-cli's host control socket as an MCP server. Any MCP-compatible AI agent can then send touch coordinates, read clipboard content, trigger hardware key events, and capture screenshots from the running VM, enabling fully automated AI-driven end-to-end test workflows.
Similar open-source tools#
hysteria
Fast and censorship-resistant proxy solution
ipatool
Search and download IPA files for iOS, iPadOS, tvOS, and visionOS
tailcat
Encrypted tunnels between machines, no account or IP needed
kudu
Terminal UI for QEMU/KVM VMs on Linux, no libvirt required
airstats
Sixteen macOS metrics in your menu bar at 0.046% CPU
OpenLogi
Local-first Logitech control without accounts or telemetry