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

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, 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) 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), which couples a manifest with helper utilities for boot layout resolution and firmware selection.

Virtual Machine Orchestration

The VPhoneVirtualMachine class in 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) 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) and VPhoneNetworking (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 leverages VPhoneCore to resolve, instantiate, and control a virtual machine:

// 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, 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), bundle discovery (VPhoneLibrary.swift), and runtime orchestration (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, while process control resides in VPhoneVirtualMachine.swift and 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}