# What Is the VPhoneCore Swift Package in vphone-cli? The VM Management Engine Explained

> Discover VPhoneCore, the core Swift package in vphone-cli. It simplifies creating, configuring, and managing virtual iPhones by abstracting Apple's Virtualization Framework.

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

---

**VPhoneCore is the central Swift library that encapsulates all logic for creating, configuring, and managing virtual iPhone instances in vphone-cli, abstracting Apple's Virtualization Framework APIs into a clean, testable interface that powers every CLI command.**

The `vphone-cli` project by Lakr233 provides command-line control of virtual iOS devices on Apple Silicon Macs. At its heart lies the **VPhoneCore Swift package**, a pure Swift module that isolates all Virtualization Framework interactions from the command-line interface. This architectural separation allows the CLI tools to remain thin argument parsers while the core handles complex VM lifecycle management, persistence, and hardware configuration.

## Core Responsibilities of the VPhoneCore Package

VPhoneCore consolidates six major domains of functionality required to run a virtual iPhone. Each domain maps to specific source files in the `sources/VPhoneCore/` directory.

### VM Manifest Handling and Persistence

The `VPhoneVirtualMachineManifest` struct defines the on-disk representation of a virtual machine. Located in [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift), this type encapsulates the plist-based configuration schema covering CPU count, memory allocation, screen resolution, network settings, storage devices, and ROM attachments. It provides helper methods for JSON conversion, URL resolution, and safe atomic updates to prevent configuration corruption during concurrent access.

### Library and Bundle Management

Virtual machines reside as bundles in the user's library directory (`~/.vphone/VMs`). The `VPhoneLibrary` class ([`VPhoneLibrary.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneLibrary.swift)) resolves this root path, enumerates available bundles, and validates their integrity, reporting specific errors such as duplicate VM names or missing manifest files. Each discovered bundle is represented by the `VPhoneBundle` type ([`VPhoneBundle.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBundle.swift)), which couples a manifest with helper utilities for boot layout resolution and firmware selection.

### Virtual Machine Orchestration

The `VPhoneVirtualMachine` class in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) translates manifest definitions into actionable Virtualization Framework configurations. It constructs a `VZVirtualMachineConfiguration`, registers device attachments for storage and network interfaces, and drives the VM lifecycle through start and stop operations. This class bridges the gap between the declarative manifest format and Apple's imperative `VZVirtualMachine` APIs.

### User Interaction and Control Utilities

Beyond core VM management, VPhoneCore provides CLI-specific helpers. `VPhoneVMPicker` ([`VPhoneVMPicker.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMPicker.swift)) handles interactive VM name resolution when users omit explicit arguments. The `VPhoneControl` class establishes vsock connections to the guest daemon for post-boot communication, while `VPhoneVerbosity` ([`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift)) and `VPhoneNetworking` ([`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift)) standardize logging levels and network utilities across the codebase.

## How vphone-cli Integrates with VPhoneCore

Every command-line entry point—whether `VPhoneVMCreateCLI`, `VPhoneVMCLI`, or `VPhoneSetupCLI`—imports the VPhoneCore package and delegates heavy lifting to its APIs. This integration follows a consistent pattern: discover or create a bundle via `VPhoneLibrary`, load the manifest through `VPhoneBundle`, instantiate the VM using `VPhoneVirtualMachine`, and control it through `VPhoneControl`.

### Typical Usage Flow in the CLI

The following Swift code illustrates how [`VPhoneVMCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMCLI.swift) leverages VPhoneCore to resolve, instantiate, and control a virtual machine:

```swift
// 1️⃣ Resolve a VM name (interactive or via argument)
let vmName = try VPhoneVMPicker.resolve(
    provided: cliArgs.name,
    names: library.bundles().map(\.name),
    libraryRoot: library.root.path,
    isInteractive: stdin.isTerminal,
    read: { readLine() },
    write: { FileHandle.standardError.write($0.data(using: .utf8)!) }
)

// 2️⃣ Load the VM bundle and its manifest
let bundle = try library.bundle(named: vmName)
let manifest = try bundle.loadManifest()

// 3️⃣ Create the virtual machine from the manifest
let vm = try VPhoneVirtualMachine(manifest: manifest, bundleURL: bundle.url)

// 4️⃣ Start the VM – the core handles all Virtualization framework setup
try vm.start()

// 5️⃣ Interact with the guest daemon over vsock (host side)
let control = VPhoneControl(vm: vm)
try control.ping()

```

By centralizing these operations in VPhoneCore, the CLI layer avoids direct dependencies on the Virtualization Framework, remaining focused solely on argument parsing and result formatting.

## Cross-Target Reusability and Testing

As defined in [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift), VPhoneCore compiles as a pure Swift module without AppKit or SwiftUI dependencies. This design choice enables comprehensive unit testing via the `VPhoneCoreTests` target and allows reuse by auxiliary tools such as the `FirmwarePatcher`. The decoupling ensures that VM logic can be validated outside the CLI context and embedded into other utilities that require virtual machine manipulation.

## Summary

- **VPhoneCore** is the foundational Swift package in `Lakr233/vphone-cli` that abstracts all Virtualization Framework complexity into a reusable library.
- It manages **VM manifests** ([`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift)), **bundle discovery** ([`VPhoneLibrary.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneLibrary.swift)), and **runtime orchestration** ([`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift)).
- The CLI tools remain thin wrappers that import VPhoneCore and delegate to its well-defined APIs for create, read, update, and delete operations.
- The package is **platform-pure Swift**, enabling unit testing and reuse by the `FirmwarePatcher` target without GUI framework dependencies.
- All persistence logic lives in [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift), while process control resides in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) and [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift).

## Frequently Asked Questions

### What file formats does VPhoneCore use to store VM configurations?

VPhoneCore uses standard property list (plist) files to persist VM configurations on disk, defined by the `VPhoneVirtualMachineManifest` type in [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift). The manifest tracks hardware parameters including CPU cores, memory allocation, screen resolution, and attached storage devices in a structured, human-readable format that supports JSON conversion for debugging and migration.

### Can VPhoneCore be used independently of the vphone-cli command-line tool?

Yes. Because VPhoneCore is defined as a separate Swift package target in [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) with no dependencies on AppKit or SwiftUI, it can be imported and used by other Swift executables or libraries. The `FirmwarePatcher` target within the same repository demonstrates this reusability, consuming VPhoneCore APIs to manipulate virtual machine bundles without invoking the CLI front-end.

### How does VPhoneCore handle interactive user selection when multiple VMs exist?

The `VPhoneVMPicker` class in [`VPhoneVMPicker.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMPicker.swift) provides interactive resolution logic. When a user omits a VM name argument or provides an ambiguous identifier, the picker enumerates available bundles from `VPhoneLibrary`, presents them via standard input/output streams, and validates the selection against the library directory before returning a confirmed name string to the calling CLI command.

### Where does VPhoneCore store virtual machine bundles by default?

VPhoneCore stores VM bundles in the `.vphone/VMs` directory within the user's home folder (`~/.vphone/VMs`). The `VPhoneLibrary` class resolves this path, validates directory permissions, and manages bundle enumeration, ensuring that all VM metadata and disk images remain isolated in a predictable location accessible to both the CLI and any tools importing the VPhoneCore package.