Building from Source

Name: GhostVM
Author: GhostVM

Build GhostVM from source to contribute or run a development version.

Prerequisites

macOS 15+ (Sequoia) on Apple Silicon (M1 or later)
Xcode 15+
XcodeGen

brew install xcodegen

Clone and Build

git clone https://github.com/groundwater/GhostVM
cd ghostvm
make app

This generates the Xcode project from project.yml and builds the app. The built app is placed in build/.

Code Signing

GhostVM requires the com.apple.security.virtualization entitlement to use Apple's Virtualization.framework. The build automatically signs the app with your local Apple Development certificate.

You need a valid Apple Developer identity in your keychain. Verify you have one with:

security find-identity -v -p codesigning

Look for a line containing Apple Development. If you don't have one, open Xcode, go to Settings → Accounts, and sign in with your Apple ID — Xcode will create the certificate automatically.

To override the signing identity, pass CODESIGN_ID:

make app CODESIGN_ID="Apple Development: [email protected] (TEAMID)"

Ad-hoc signing won't work

Ad-hoc signed builds (-s "-") cannot use the virtualization entitlement. You must sign with a real Apple Development certificate or the app will crash on launch.

Make Targets

Target	Description
`make app`	Build the GUI app (auto-generates Xcode project)
`make cli`	Build the `vmctl` CLI tool
`make generate`	Generate the Xcode project from `project.yml`
`make run`	Build and run attached to terminal
`make launch`	Build and launch detached
`make test`	Run unit tests
`make clean`	Remove build artifacts and generated project

XcodeGen

The Xcode project is generated from project.yml using XcodeGen. Do not edit GhostVM.xcodeproj directly — your changes will be overwritten on the next make generate.

Architecture