# vphone-cli Architecture Explained: How the Virtual iPhone Emulator Works

> Explore the vphone-cli architecture, a layered Swift design leveraging Virtualization.framework for VM management, guest communication, UI, and firmware patching.

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

---

**vphone-cli uses a layered Swift architecture built on Apple's Virtualization.framework, separating VM lifecycle management, vsock-based guest communication, UI handling, firmware patching, and auxiliary utilities into distinct subsystems.**

`vphone-cli` is a Swift-only macOS application that creates, configures, and boots virtual iPhone VMs using Apple's **Virtualization.framework**. Its architecture follows a modular design with clear separation of concerns, making the codebase testable and extensible. This article examines each architectural layer as implemented in the [Lakr233/vphone-cli](https://github.com/Lakr233/vphone-cli) repository.

## Entry Point and Application Lifecycle

The application bootstrap follows standard Cocoa patterns with dedicated components for CLI parsing and app delegation.

- **[`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift)** — Parses command-line arguments and launches the `NSApplication`
- **[`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift)** — Sets up the app, handles `SIGINT`, and orchestrates VM start/stop

The delegate instantiates `VPhoneVirtualMachine`, injects parsed options, and presents the main window via `VPhoneWindowController`. Both entry point files reside in `sources/vphone-cli/`.

## Virtual Machine Core

The VM subsystem wraps Apple's `VZVirtualMachine` APIs and configures virtual hardware through private framework calls.

### Core VM Components

| Component | Responsibility | Source File |
|-----------|---------------|-------------|
| `VPhoneVirtualMachine` | Wraps `VZVirtualMachineConfiguration`, implements `start()` and `stop()` lifecycle methods | [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) |
| `VPhoneHardwareModel` | Describes virtual hardware (CPU, GPU, memory) using the **Dynamic** library for private API access | [`sources/vphone-cli/VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneHardwareModel.swift) |
| `VPhoneVirtualMachineView` | `NSView` subclass rendering the VM display and forwarding input events | [`sources/vphone-cli/VPhoneVirtualMachineView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachineView.swift) |

All VM-related classes carry `@MainActor` annotations to maintain UI state consistency across asynchronous operations.

## Guest-Daemon Communication (vsock)

A custom protocol enables bidirectional communication between host macOS and the guest iOS VM.

### Host-Side Client Stack

- **[`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift)** — Host-side client connecting to the in-VM daemon (`vphoned`) over **vsock port 1337**. Implements a length-prefixed JSON protocol with auto-reconnect and request/response mapping
- **[`VPhoneHostControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHostControl.swift)** — Higher-level helper forwarding host commands (IPA installation, file operations) to the daemon

This subsystem powers features including IPA installation, file browser uploads/downloads, location syncing, and remote command execution. The vsock approach avoids network stack dependencies, providing reliable VM-host communication.

## UI and Menu System

The interface layer combines AppKit components with SwiftUI views for specific workflows.

### Window and Menu Infrastructure

- **[`VPhoneWindowController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneWindowController.swift)** — Hosts the VM view, toolbar, and menu bar orchestration
- **[`VPhoneMenuController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuController.swift)** — Central registry and dispatcher for all menu extensions

### Specialized Menu Modules

Individual `VPhoneMenu*` classes handle specific feature categories:

- `VPhoneMenuKeys` — Keyboard input handling
- `VPhoneMenuLocation` — GPS/location controls
- `VPhoneMenuConnect` — Connection management
- `VPhoneMenuInstall` — IPA installation interface
- `VPhoneMenuRecord` — Screen recording controls
- `VPhoneMenuBattery` — Battery state management

- **[`VPhoneKeyHelper.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneKeyHelper.swift)** — Translates macOS key events into VM key presses (home, power, volume)

### SwiftUI File Browser

- **`VPhoneFileBrowserView`** — SwiftUI-based filesystem explorer interacting with the VM via vsock
- **`VPhoneFileBrowserModel`** — Observable object managing browser state

The menu architecture is extensible: each category registers callbacks with `VPhoneMenuController`, simplifying addition of new actions.

## Firmware and Patch Pipeline

Firmware preparation runs outside the main Swift application through a Python-based pipeline.

### Patcher Architecture

| Layer | Technology | Purpose |
|-------|-----------|---------|
| `FirmwarePatcher/` subfolders | Python | Kernel modification, device-tree patching, cryptex file manipulation |
| [`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift) | Swift | CLI frontend for pipeline invocation, firmware variant selection, and `Disk.img` generation |

The patcher produces **CFW (custom firmware)** images that the Swift client boots directly. Modular components include manifest handling, binary helpers, and device-tree patching—keeping the Swift codebase agnostic of low-level patch logic.

Variant selection includes: regular, developer, jailbreak, and experimental firmware builds.

## IPA Installation and Code Signing

Application deployment requires extraction, re-signing, and streaming to the VM.

- **[`VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneIPAInstaller.swift)** — Extracts IPA archives, re-signs Mach-O binaries, and streams payloads via `VPhoneControl`
- **[`VPhoneSigner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneSigner.swift)** — Low-level Mach-O signing with `codesign`-compatible hashes and private entitlements handling

The installation flow validates bundle structure, applies necessary entitlements for VM execution, and transfers files through the established vsock connection.

## Auxiliary Utilities

Additional components support extended workflows:

- **[`VPhoneScreenRecorder.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneScreenRecorder.swift)** — Captures VM display frames and writes video files
- **[`VPhoneLocationProvider.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneLocationProvider.swift)** — Bridges macOS CoreLocation into the VM via vsock daemon
- **[`VPhoneProgressBar.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneProgressBar.swift)** — UI feedback for long operations (firmware download, patching, installation)

## Core Helpers (VPhoneCore)

A shared library (`VPhoneCore`) contains reusable utilities consumed by both UI and CLI code:

- [`VPhoneProcessRunner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneProcessRunner.swift) — Process execution and management
- [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift) — Network utilities
- [`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift) — Logging and debug output control
- [`VPhoneVMPicker.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMPicker.swift) — VM selection interface
- [`VPhoneFirmwareCatalog.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFirmwareCatalog.swift) — Firmware metadata and availability

## Architecture Flow

The complete vphone-cli architecture operates through this sequence:

1. **CLI parsing** (`VPhoneCLI`) → `VPhoneAppDelegate` initialization
2. **VM configuration** via `VPhoneVirtualMachine` and `VPhoneHardwareModel`
3. **VM launch** with `VPhoneVirtualMachineView` rendering display
4. **Guest daemon** (`vphoned`) starts inside iOS VM, listens on vsock
5. **Host vsock client** (`VPhoneControl`) connects, exposing high-level APIs
6. **User interaction** through menus, shortcuts, or SwiftUI file browser
7. **Optional firmware patching** pre-boot to generate custom CFW images

The UI layer never directly manipulates VM state—all operations route through the control layer to the vsock daemon. This loose coupling enables unit testing (see `tests/` directory) and future extension.

## Code Examples

### Launch a VM from Command Line

```bash
vphone-cli boot --firmware regular --cpu 4 --memory 4096

```

The `boot` subcommand creates `VPhoneVirtualMachine.Options`, configures hardware, and calls `VPhoneVirtualMachine.start()`.

### Install an IPA Programmatically

```swift
import VPhoneCLI

let installer = VPhoneIPAInstaller()
try installer.installIPA(
    at: "/path/to/MyApp.ipa",
    into: vm,                // VPhoneVirtualMachine instance
    using: VPhoneControl()    // vsock client
)

```

### Retrieve a Remote File from the VM

```swift
let control = VPhoneControl()
let remotePath = "/var/mobile/Containers/Data/Application/UUID/Documents/config.json"
let data = try await control.fetchFile(at: remotePath)
print(String(decoding: data, as: UTF8.self))

```

### SwiftUI File Browser Integration

```swift
import SwiftUI
import VPhoneCLI

struct ContentView: View {
    @StateObject private var model = VPhoneFileBrowserModel()
    
    var body: some View {
        VPhoneFileBrowserView(model: model)
    }
}

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`sources/vphone-cli/VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneAppDelegate.swift) | Application lifecycle and VM orchestration |
| [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) | Core `VZVirtualMachine` wrapper |
| [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift) | Host-side vsock JSON protocol client |
| [`sources/vphone-cli/VPhoneMenuController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneMenuController.swift) | Central menu registry |
| [`sources/vphone-cli/VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneIPAInstaller.swift) | IPA extraction and installation |
| [`sources/vphone-cli/VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneFWCLI.swift) | Firmware patch pipeline frontend |
| [`sources/vphone-cli/VPhoneFileBrowserView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneFileBrowserView.swift) | SwiftUI filesystem browser |
| [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) | SwiftPM dependencies and targets |

## Summary

- **vphone-cli** implements a modular Swift architecture on Virtualization.framework with strict separation between VM core, communication, UI, and firmware layers
- **vsock-based JSON protocol** (port 1337) provides reliable host-guest communication without network dependencies
- **Python patch pipeline** handles low-level firmware modification while Swift manages VM lifecycle
- **Extensible menu system** uses registered callbacks for straightforward feature addition
- **`@MainActor` annotations** ensure thread-safe UI state across asynchronous VM operations

## Frequently Asked Questions

### What frameworks does vphone-cli depend on?

vphone-cli builds on Apple's **Virtualization.framework** for VM management, **Dynamic** library for private API access to hardware configuration, and standard Cocoa/SwiftUI for interface components. The guest daemon uses vsock (virtual socket) facilities exposed through the virtualization layer.

### How does vphone-cli communicate with the iOS VM?

Communication uses a **custom length-prefixed JSON protocol** over **vsock port 1337**. The host-side `VPhoneControl` class manages connection lifecycle, auto-reconnect, and request routing to the in-VM `vphoned` daemon. This design avoids TCP/IP overhead and provides reliable local communication.

### Can vphone-cli run unmodified iOS firmware?

No—the firmware requires **custom patching** through the Python-based `FirmwarePatcher` pipeline. The patcher modifies the kernel, device-tree, and cryptex files to enable VM boot. The Swift application ([`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift)) selects firmware variants and invokes the patch pipeline, but does not directly manipulate binary patching logic.

### Is the vphone-cli menu system customizable?

Yes. The architecture uses a **central registry pattern**: `VPhoneMenuController` maintains callbacks from specialized `VPhoneMenu*` classes (`VPhoneMenuKeys`, `VPhoneMenuLocation`, etc.). Adding new menu items requires implementing the callback interface and registering with the controller, without modifying existing menu code.