# How to Run vphone-cli: A Complete Guide to Virtualizing iOS on macOS

> Learn how to run vphone-cli to virtualize iOS on macOS. Build the Swift binary, prepare firmware, and create a VM with simple commands.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**Run vphone-cli by building the Swift binary from source, preparing a patched iOS firmware bundle, and launching a virtual machine using the `vphone-cli vm create` command.**

vphone-cli is a Swift-based command-line tool that creates, patches, and boots virtual iPhones using Apple's Virtualization.framework. The project, hosted at `Lakr233/vphone-cli`, orchestrates firmware downloads, binary patching, and VM lifecycle management through a hierarchical CLI interface defined in [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift).

## Prerequisites and System Requirements

Before you run vphone-cli, ensure your host meets the following requirements:

- **macOS 15 or later** (Sequoia) is required for full Virtualization.framework compatibility
- **Apple Silicon Mac** (M-series chip) recommended for optimal performance with the SEP (Secure Enclave Processor) emulation
- **Homebrew** installed for dependency management
- Approximately **50GB of free disk space** for IPSW downloads, extracted firmware, and VM bundles

Install the required host dependencies via Homebrew:

```bash
brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus \
    sshpass keystone cmake libusb ipsw zstd

```

## Building vphone-cli from Source

vphone-cli must be compiled from source as it requires code signing with private entitlements to interact with the Virtualization.framework. The build process involves two main scripts located in the `scripts/` directory.

### Clone the Repository and Initialize Submodules

Clone the repository with all submodules to ensure you have the `FirmwarePatcher` package and guest daemon source:

```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
cd vphone-cli

```

### Run the Setup Script

Execute [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) to install sub-modules, download required toolchains, and create the Python virtual environment (`.venv`) used by the patching pipeline:

```bash
./scripts/setup_tools.sh

```

This script prepares the environment for the firmware patching operations handled by `PatchFirmwareCLI` in [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift).

### Compile and Sign the Binary

Run [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) to build the Swift executable, sign it with the necessary entitlements, and bundle the `.app` structure:

```bash
./scripts/build.sh

```

The compiled binary will be available at `.build/vphone-cli.app/Contents/MacOS/vphone-cli`. You can either navigate to this directory or add it to your PATH.

## Creating and Launching Your First Virtual iPhone

The CLI exposes sub-commands that map to three logical layers: firmware preparation, patching, and VM management. The entry point in [`sources/vphone-cli/main.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/main.swift) parses commands and dispatches to handlers like `VPhoneVMCommand` and `VPhoneFWCommand`.

### Quick Start with One Command

For immediate results, use the high-level shortcut that automates the entire pipeline:

```bash
vphone-cli vm create myphone -V jb
vphone-cli vm launch myphone

```

The `vm create` command performs the following actions sequentially:
1. Downloads the appropriate IPSW for the specified variant (here, `jb` for jailbreak)
2. Executes the `FirmwarePipeline` (Swift-only implementation in the `FirmwarePatcher` package) to merge cloudOS and apply binary patches
3. Patches the boot-chain, TXM, and kernel as defined in `PatchFirmwareCLI`
4. Performs a DFU restore and installs the custom firmware (CFW)

### Manual Firmware Pipeline (Alternative)

For fine-grained control over the patching process, execute each stage manually:

```bash

# Initialize an empty VM bundle

vphone-cli vm new myphone

# Download and prepare firmware for iOS 26.1

vphone-cli fw prepare myphone --iphone-version 26.1

# Apply jailbreak patches

vphone-cli fw patch myphone --variant jb

# Boot into DFU mode for restoration (backgrounded)

vphone-cli vm launch myphone --dfu &

# Capture SHSH blobs and perform DFU restore

vphone-cli restore myphone --get-shsh
vphone-cli restore myphone

# Stop the DFU boot process

vphone-cli vm stop myphone

# Install custom firmware (requires sudo for mounting)

vphone-cli cfw install myphone --variant jb

# Final boot into normal GUI mode

vphone-cli vm launch myphone

```

This manual approach lets you inspect intermediate artifacts and customize patch parameters defined in [`research/0_binary_patch_comparison.md`](https://github.com/Lakr233/vphone-cli/blob/main/research/0_binary_patch_comparison.md).

## Managing the Virtual Machine Lifecycle

Once built, VMs are managed through [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), which wraps `VZVirtualMachineConfiguration` to configure CPU, memory, disk, SEP, and screen parameters.

### Booting in Different Modes

vphone-cli supports multiple boot modes via the `VPhoneVirtualMachine` class:

- **GUI Mode**: Default interactive mode with graphical display (requires `NSApplication` lifecycle as implemented in [`main.swift`](https://github.com/Lakr233/vphone-cli/blob/main/main.swift))
- **DFU Mode**: Headless device firmware update mode for restoration operations (`--dfu` flag)
- **Headless Mode**: Background operation without display attachment

Stop a running VM gracefully:

```bash
vphone-cli vm stop myphone

```

### Connecting to the Running Instance

After launching, connect to your virtual iPhone using standard networking:

```bash

# SSH as mobile user (jailbreak environment, password: alpine)

ssh -p 22222 mobile@<vm-ip>

# SSH as root (development environment)

ssh -p 22222 root@<vm-ip>

# VNC graphical console

open vnc://<vm-ip>:5901

```

The SSH and VNC services are forwarded through the virtual network interface configured by `VZVirtualMachine`.

## Summary

- **vphone-cli** is a Swift CLI tool for virtualizing iOS on macOS 15+ using Apple's Virtualization.framework.
- **Build process** relies on [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) for dependencies and [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) for compilation and code signing.
- **Firmware pipeline** in [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift) handles IPSW downloads, binary patching (TXM, kernel, boot-chain), and bundle creation.
- **VM lifecycle** is managed via [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), supporting GUI, DFU, and headless boot modes.
- **Quick start** uses `vphone-cli vm create <name> -V <variant>` to automate the entire workflow.
- **Access methods** include SSH on port 22222 (mobile/alpine or root) and VNC on port 5901.

## Frequently Asked Questions

### What macOS version do I need to run vphone-cli?

You need **macOS 15 (Sequoia) or later**. The tool depends on specific APIs in Apple's Virtualization.framework that are only available in macOS 15+, particularly for SEP (Secure Enclave Processor) emulation and the PV (Platform Version) 3 virtualization layer.

### How do I jailbreak the virtual iPhone?

Use the `jb` variant flag during creation or patching: `vphone-cli vm create myphone -V jb` or `vphone-cli fw patch myphone --variant jb`. According to the source code in [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift), this applies the jailbreak-specific binary patches to the kernel and userspace components, enabling the `mobile` user SSH access with password `alpine` on port 22222.

### Can I run multiple virtual iPhones simultaneously?

While the Virtualization.framework supports multiple VMs, vphone-cli manages VM state through named bundles in the working directory. Each VM requires significant resources (disk, memory, CPU cores). You can create multiple instances with different names using `vphone-cli vm new <name>`, but ensure your host has sufficient RAM and CPU overhead for concurrent SEP emulation.

### Where are the VM bundles and firmware stored?

VM bundles are created as directories in your current working directory when you run `vphone-cli vm new` or `vphone-cli vm create`. These bundles contain the virtual disk images, NVRAM, and configuration. Downloaded IPSWs and intermediate patched firmware components are cached within the project structure or system temp directories, depending on the `FirmwarePipeline` implementation in the `FirmwarePatcher` package.