# How to Install vphone-cli on Apple Silicon: Homebrew and Build-from-Source Guide

> Easily install vphone-cli on Apple Silicon using Homebrew or build from source. Follow our guide for macOS 15 Sequoia and later. Get vphone-cli running quickly.

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

---

**You can install vphone-cli on macOS 15 Sequoia or later using Homebrew (`brew install zqxwce/tap/vphone-cli`) or by cloning the Lakr233/vphone-cli repository, running [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh), and executing [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) to produce a signed binary at `.build/vphone-cli.app/Contents/MacOS/vphone-cli`.**

vphone-cli is a Swift 6.0 command-line tool that leverages Apple’s Virtualization.framework to boot virtual iPhones on Apple Silicon Macs. The repository provides both a pre-built Homebrew formula and a complete build pipeline for local compilation. This guide covers both installation methods, the mandatory system prerequisites, and how to verify your setup before creating your first VM.

## Prerequisites for Installing vphone-cli

Before installing vphone-cli, ensure your host system meets the strict hardware and software requirements enforced by the Virtualization.framework and the tool’s jailbreak components.

### Hardware and Software Requirements

vphone-cli requires Apple Silicon (M-series chips) and cannot run on Intel Macs. You must have macOS 15 Sequoia or later installed, along with the full Xcode application—not just the command-line tools—to access the iOS SDK required for cross-compiling the guest daemon. The virtualization stack relies on specific entitlements and frameworks only available on Apple Silicon running macOS 15+.

### SIP and AMFI Configuration

System Integrity Protection (SIP) and AMFI must be relaxed to allow the virtual machine’s boot chain patching and trust cache injection. According to the Lakr233/vphone-cli source documentation, these security relaxations are mandatory for the binary to function correctly whether you use the Homebrew distribution or build from source. Refer to the repository’s README for the exact `csrutil` and boot-args commands required before proceeding with installation.

## Install vphone-cli via Homebrew (Recommended)

The fastest way to install vphone-cli uses the third-party Homebrew tap maintained by the project. This method downloads the latest pre-built, signed binary and installs the `vphone-cli` command into your PATH without requiring local compilation.

Run the following command in Terminal:

```bash
brew install zqxwce/tap/vphone-cli

```

Homebrew handles the entitlements and code signing automatically, placing the executable in your environment. After installation completes, proceed to the verification step to confirm the binary is accessible.

## Build vphone-cli from Source

If you need to modify the source code in [`sources/vphone-cli/main.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/main.swift) or debug the [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) configuration logic, building locally provides full control over the compilation process.

### Clone the Repository

First, clone the repository including all necessary submodules:

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

```

The `--recurse-submodules` flag is critical as the project depends on external components for the guest daemon and virtualization helpers.

### Run Setup Scripts

Prepare the build environment by executing the setup script, which installs runtime dependencies including `trustcache`, `insert_dylib`, and configures the Python virtual environment:

```bash
./scripts/setup_tools.sh

```

This script automates the installation of tools required by the build pipeline and guest environment preparation.

### Build the Application Bundle

Compile the Swift executable and generate the signed `.app` bundle using the build script:

```bash
./scripts/build.sh

```

The script compiles [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift) (which implements the ArgumentParser-based command interface) along with [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift) and [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) to produce the final binary. Upon completion, the signed executable resides at:

```

.build/vphone-cli.app/Contents/MacOS/vphone-cli

```

You can either run the binary directly from this path or symlink it to a directory in your PATH for global access.

## Verify Your Installation

Regardless of installation method, confirm that vphone-cli is correctly installed and accessible by invoking the help command:

```bash
vphone-cli --help

```

You should see the command-line interface options including the `vm create` and `vm launch` commands implemented in [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift). Successful output indicates that the binary, entitlements, and Virtualization.framework dependencies are properly configured.

## Next Steps: Creating Your First Virtual iPhone

Once installation is verified, initialize your first virtual machine using the jailbreak variant:

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

```

These commands trigger the full provisioning pipeline: downloading IPSWs, patching the boot chain, performing a DFU restore, installing the custom firmware, and booting the virtualized iOS environment through the `VZVirtualMachineConfiguration` defined in the source.

## Summary

- **vphone-cli** requires Apple Silicon running macOS 15+ with Xcode and SIP/AMFI relaxation
- **Homebrew installation** uses `brew install zqxwce/tap/vphone-cli` for immediate deployment
- **Source builds** require cloning with submodules, running [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh), then [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh)
- The compiled binary outputs to `.build/vphone-cli.app/Contents/MacOS/vphone-cli`
- **Key source files** include [`main.swift`](https://github.com/Lakr233/vphone-cli/blob/main/main.swift), [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), and [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift)
- Verify installation with `vphone-cli --help` before creating VMs

## Frequently Asked Questions

### Can I install vphone-cli on Intel Macs?

No, vphone-cli is exclusively compatible with Apple Silicon (M1, M2, M3, and later). The tool relies on Apple’s Virtualization.framework and specific CPU virtualization features only present in M-series chips. Attempting to build or run the tool on Intel architectures will fail during compilation or runtime.

### Why do I need to disable SIP and AMFI?

The virtualization process requires modifying system-level trust caches and injecting dynamic libraries into the virtualized iOS kernel, operations that macOS security frameworks normally block. Disabling SIP (System Integrity Protection) and relaxing AMFI (Apple Mobile File Integrity) allows `vphone-cli` to patch the secure boot chain and manage the VM’s hardware virtualization layer as implemented in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift).

### Where is the vphone-cli binary located when building from source?

When compiling manually, the signed executable is placed at `.build/vphone-cli.app/Contents/MacOS/vphone-cli` relative to the repository root. This path contains the Swift 6.0 binary built by [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) along with necessary entitlements and bundle resources required for Virtualization.framework access.

### How do I update vphone-cli to the latest version?

If installed via Homebrew, run `brew upgrade zqxwce/tap/vphone-cli` to fetch the latest pre-built release. For source installations, pull the latest changes with `git pull --recurse-submodules` and re-run [`scripts/build.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/build.sh) to recompile the binary with the updated source from `sources/vphone-cli/`.