# Understanding the vphone-cli Architecture: A Modular Swift Virtualization Framework for iOS VMs

> Explore the vphone-cli architecture, a modular Swift framework leveraging Virtualization.framework for iOS VMs. Understand its layered design for VM management, guest communication, and UI.

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

---

**The vphone-cli architecture is a modular, layered Swift system built on Apple's Virtualization.framework, separating VM lifecycle management, guest-daemon communication via vsock, UI/menu handling, and firmware patching into loosely coupled subsystems.**

vphone-cli is a Swift-only macOS application that creates, configures, and boots virtual iPhone VMs. Its architecture deliberately isolates concerns across eight primary layers, making the codebase testable, extensible, and maintainable. Every major component lives in the `sources/vphone-cli/` directory, with additional Python-based firmware patchers in `sources/FirmwarePatcher/`.

## Entry Point and Application Lifecycle

The application bootstrap follows standard macOS patterns with custom VM orchestration layered on top.

### VPhoneCLI.swift – Command-Line Parser

Located at [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift), this file parses arguments and launches the `NSApplication`. It transforms CLI flags into structured options passed to the delegate.

### VPhoneAppDelegate.swift – Lifecycle Orchestrator

[`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift) handles the critical startup sequence:

- Configures `NSApplication` and registers SIGINT handlers
- Creates `VPhoneVirtualMachine` with injected options
- Instantiates `VPhoneWindowController` for the main window

The delegate serves as the central coordinator, bridging user intent (CLI or UI) with VM execution.

## Virtual Machine Core

The VM layer wraps Apple's `VZVirtualMachine` with vphone-cli-specific configuration and lifecycle management. All classes here use `@MainActor` annotation to ensure UI consistency.

### VPhoneVirtualMachine.swift

This core wrapper in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) manages:

- `VZVirtualMachineConfiguration` assembly
- Hardware model integration from `VPhoneHardwareModel`
- Lifecycle methods: `start()`, `stop()`, and state observation

### VPhoneHardwareModel.swift

Located at [`sources/vphone-cli/VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneHardwareModel.swift), this component describes virtual CPU, GPU, memory, and device topology. It uses the **Dynamic** library to call private Apple APIs for hardware model selection.

### VPhoneVirtualMachineView.swift

[`VPhoneVirtualMachineView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineView.swift) provides an `NSView` subclass wrapping `VZVirtualMachineView`, handling display rendering and input event forwarding from macOS to the guest iOS system.

## Guest-Daemon Communication (vsock)

Communication with the running iOS VM occurs over vsock (port 1337) using a length-prefixed JSON protocol.

### VPhoneControl.swift

The host-side client in [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift) implements:

- Automatic reconnection to the in-VM `vphoned` daemon
- Request/response mapping with structured JSON
- Low-level vsock socket management

### VPhoneHostControl.swift

[`VPhoneHostControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHostControl.swift) acts as a convenience layer, exposing high-level host commands:

- IPA installation forwarding
- File retrieval and upload
- Location synchronization
- Remote shell execution

This subsystem enables the full feature set: file browsing, app installation, location spoofing, and command execution without direct VM manipulation.

## UI and Menu System

The interface layer separates window management, menu registration, and specialized interaction handlers.

### VPhoneWindowController.swift

[`VPhoneWindowController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneWindowController.swift) hosts the VM view, toolbar configuration, and menu bar orchestration.

### VPhoneMenuController.swift

The central hub at [`sources/vphone-cli/VPhoneMenuController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneMenuController.swift) maintains a registry of menu extensions. Each category registers callbacks here, enabling dynamic menu construction.

### Specialized Menu Components

Individual files handle specific feature categories:

- [`VPhoneMenuKeys.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuKeys.swift) – Hardware key simulation
- [`VPhoneMenuLocation.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuLocation.swift) – GPS/location controls
- [`VPhoneMenuConnect.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuConnect.swift) – Connection state
- [`VPhoneMenuInstall.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuInstall.swift) – IPA installation UI
- [`VPhoneMenuRecord.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuRecord.swift) – Screen recording controls
- [`VPhoneMenuBattery.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuBattery.swift) – Battery state simulation

### VPhoneKeyHelper.swift

[`VPhoneKeyHelper.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneKeyHelper.swift) translates macOS `NSEvent` key events into VM key presses for home, power, volume, and other hardware buttons.

### SwiftUI File Browser

The `VPhoneFileBrowser*` files implement a complete file manager:

- [`VPhoneFileBrowserView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFileBrowserView.swift) – SwiftUI view layer
- [`VPhoneFileBrowserWindow.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFileBrowserWindow.swift) – Window container
- [`VPhoneFileBrowserModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFileBrowserModel.swift) – Observable data model

These components bind to `VPhoneControl` for directory listing, upload, and download operations via the vsock daemon.

## Firmware and Patch Pipeline

Firmware preparation runs external to the running VM through a hybrid Python/Swift pipeline.

### Python-Based FirmwarePatcher

Located under `sources/FirmwarePatcher/`, these patchers modify:

- iOS kernel images
- Device tree blobs
- Cryptex files

The Swift side remains agnostic to patch implementation details, consuming only the final CFW (custom firmware) image.

### VPhoneFWCLI.swift

[`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift) provides the CLI frontend for firmware operations:

- Variant selection (regular, developer, jailbreak, experimental)
- Patch pipeline invocation
- `Disk.img` generation

The modular patcher design allows new firmware variants without client code changes.

## IPA Installation and Code Signing

### VPhoneIPAInstaller.swift

[`VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneIPAInstaller.swift) at [`sources/vphone-cli/VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneIPAInstaller.swift) handles the complete installation flow:

1. IPA extraction
2. Mach-O binary re-signing via `VPhoneSigner`
3. Payload streaming to VM through `VPhoneControl`

### VPhoneSigner.swift

[`VPhoneSigner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneSigner.swift) implements low-level Mach-O signing with `codesign`-compatible hashes and private entitlement injection.

## Auxiliary Utilities

Supporting functionality spans several focused components:

- **VPhoneScreenRecorder.swift** – Frame capture and video encoding
- **VPhoneLocationProvider.swift** – macOS CoreLocation bridging to VM
- **VPhoneProgressBar.swift** – Visual feedback for long operations

## Core Helpers (VPhoneCore)

The shared `VPhoneCore` library contains reusable infrastructure:

| Component | Responsibility |
|-----------|---------------|
| [`VPhoneProcessRunner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneProcessRunner.swift) | Subprocess management |
| [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift) | URL session utilities |
| [`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift) | Structured logging |
| [`VPhoneVMPicker.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMPicker.swift) | VM selection UI |
| [`VPhoneFirmwareCatalog.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFirmwareCatalog.swift) | Firmware metadata management |

These utilities serve both the Swift UI and command-line targets.

## Execution Flow

Understanding how these layers interact clarifies the architecture's loose coupling:

1. **Bootstrap** – `VPhoneCLI` parses arguments, delegates to `VPhoneAppDelegate`
2. **Configuration** – `VPhoneVirtualMachine` and `VPhoneHardwareModel` assemble `VZVirtualMachineConfiguration`
3. **Launch** – VM starts, `VPhoneVirtualMachineView` renders display
4. **Daemon startup** – `vphoned` initializes inside iOS VM, listens on vsock port 1337
5. **Control connection** – `VPhoneControl` connects, exposes high-level APIs
6. **User interaction** – Menus, keyboard shortcuts, and file browser operate through the control layer
7. **Firmware preparation** – Optional patching runs pre-boot, producing CFW image

## Code Examples

### Launching a VM Programmatically

```swift
import VPhoneCLI

let options = VPhoneVirtualMachine.Options(
    firmware: .regular,
    cpuCount: 4,
    memorySize: 4096 * 1024 * 1024
)

let vm = VPhoneVirtualMachine(options: options)
try await vm.start()

```

This creates the hardware model, configures the virtual machine, and begins execution.

### Installing an IPA via the Control Interface

```swift
let installer = VPhoneIPAInstaller()
try installer.installIPA(
    at: "/path/to/Application.ipa",
    into: vm,
    using: VPhoneControl()
)

```

The installer extracts, re-signs, and streams the payload through the vsock connection.

### Retrieving Files from the Guest

```swift
let control = VPhoneControl()
let data = try await control.fetchFile(
    at: "/var/mobile/Documents/config.plist"
)

```

`VPhoneControl` serializes the request as JSON, transmits over vsock, and returns raw bytes.

## Summary

- **vphone-cli architecture** separates VM lifecycle, vsock communication, UI, and firmware patching into distinct layers
- **Core VM layer** wraps `VZVirtualMachine` with [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift), and `@MainActor` safety
- **Guest communication** uses vsock port 1337 with [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) implementing length-prefixed JSON protocol
- **Menu system** is extensible through [`VPhoneMenuController.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuController.swift) registration pattern
- **Firmware pipeline** isolates Python patchers from Swift client via [`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift)
- **IPA installation** combines [`VPhoneSigner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneSigner.swift) Mach-O signing with [`VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneIPAInstaller.swift) streaming
- **All interactions** flow through the control layer, never direct VM manipulation, ensuring testability and extension points

## Frequently Asked Questions

### What virtualization technology does vphone-cli use?

vphone-cli builds directly on Apple's **Virtualization.framework**, the native macOS hypervisor framework. The `VPhoneVirtualMachine` class in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) wraps `VZVirtualMachine` and `VZVirtualMachineConfiguration`, using private APIs via the Dynamic library for hardware model selection.

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

Communication occurs over **vsock (socket address family 40)** on fixed port 1337. The host-side [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) connects to the in-VM `vphoned` daemon using a length-prefixed JSON protocol. This enables file transfer, IPA installation, location sync, and remote command execution without network stack dependency.

### Can vphone-cli run modified or jailbroken iOS firmware?

Yes. The **FirmwarePatcher** pipeline in `sources/FirmwarePatcher/` provides Python-based tooling to modify kernels, device trees, and cryptex files. [`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift) exposes variant selection (regular, dev, jailbreak, experimental) and orchestrates patch application before VM boot, producing a custom CFW image consumed by the virtualization layer.

### What is the role of VPhoneCore in the architecture?

**VPhoneCore** is a shared library containing reusable utilities used across the codebase: process spawning ([`VPhoneProcessRunner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneProcessRunner.swift)), networking ([`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift)), logging ([`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift)), and firmware catalog management ([`VPhoneFirmwareCatalog.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFirmwareCatalog.swift)). Both the SwiftUI application and command-line utilities depend on this layer, preventing code duplication between interfaces.