Architecture
GhostVM is composed of several components that work together to provide a complete virtualization experience on Apple Silicon.
Components
GhostVM.app (Main App)
The main SwiftUI application. Manages the VM list, creates new VMs, manages restore images, and launches VM instances. The main app doesnot run VMs directly — it delegates to GhostVMHelper.
GhostVMHelper
A separate process spawned for each running VM. Each helper gets its own Dock icon (showing the VM's custom icon) and runs the Virtualization.framework VM instance. This isolation ensures that a crashing VM doesn't take down the main app or other VMs.
GhostVMKit
A shared framework containing core types used by both the main app and the helper:
VMFileLayout— resolves paths within a .GhostVM bundleVMConfigStore— reads/writes config.jsonVMStoredConfig— Codable VM configuration modelPortForwardConfig,SharedFolderConfig— typed configurations
vmctl (CLI)
A command-line tool that provides the same capabilities as the GUI. Uses GhostVMKit for all VM operations. Supports headless operation for scripting and automation.
GhostTools (Guest Agent)
A companion app that runs inside the guest VM. Communicates with the host over virtio-vsock to provide clipboard sync, file transfer, port discovery, and health monitoring.
Host API Service
Each running VM's Helper process exposes a Unix domain socket at ~/Library/Application Support/GhostVM/api/. The socket accepts standard HTTP/1.1 requests (with JSON bodies) and provides access to guest proxy operations (clipboard, exec, files, apps). Any HTTP client that supports Unix sockets can connect. See the Host API docs for details.
Services Architecture
All host-guest services are located in GhostVM/Services/ and are @MainActor isolated. They're shared between the main app and GhostVMHelper targets.
| Service | Description |
|---|---|
HealthCheckService | Persistent vsock connection on port 5002 to detect GhostTools |
EventStreamService | Persistent vsock connection on port 5003 for guest events |
ClipboardSyncService | Event-driven clipboard sync on window focus/blur |
FileTransferService | Host-to-guest and guest-to-host file transfers |
PortForwardService | TCP-to-vsock port forwarding via NIO |
AutoPortMapService | Auto-detects guest listening ports and creates forwards |
FolderShareService | Configures VirtioFS shared folder attachments |
Communication
Host-guest communication uses virtio-vsock, a high-performance virtual socket transport provided by Virtualization.framework. This is faster and more reliable than network sockets and doesn't require guest networking to be configured.
Services use GhostClient(virtualMachine:vmQueue:) to create vsock connections to the guest.
Networking
VMs use VZNATNetworkDeviceAttachment for network access. This provides NAT networking with zero configuration overhead — the guest gets internet access through the host's network connection.