VM Bundles

GhostVM stores each virtual machine as a self-contained .GhostVM bundle — a macOS package (directory) that holds everything needed to run the VM.

Bundle Structure

MyVM.GhostVM/
├── config.json          # VM configuration (CPU, memory, disk, etc.)
├── disk.img             # Main disk image (raw sparse file)
├── MachineIdentifier    # Unique hardware ID (macOS VMs)
├── HardwareModel        # Hardware model data (macOS VMs)
├── RestoreImage.ipsw    # macOS restore image (if attached)
├── AuxiliaryStorage     # NVRAM / EFI boot state
├── icon.png             # Custom VM icon (optional)
├── SavedState/          # Suspend/resume state (if suspended)
└── Snapshots/           # Named snapshots
    ├── clean-state/
    │   ├── disk.img
    │   └── SavedState/
    └── after-setup/
        ├── disk.img
        └── SavedState/

Configuration (config.json)

The config.json file stores VM settings persisted between runs:

{
  "cpus": 6,
  "memoryBytes": 17179869184,
  "diskBytes": 137438953472,
  "guestOSType": "macOS",
  "sharedFolders": [
    { "path": "/Users/jake/Shared", "readOnly": true }
  ],
  "portForwards": [
    { "hostPort": 8080, "guestPort": 80 }
  ]
}

Disk Images

Disk images are raw sparse files. The default size is 256 GiB, but the file only consumes actual used space on the host filesystem. You can check actual disk usage with:

du -sh ~/VMs/MyVM.GhostVM/disk.img

Portability

Bundles are fully portable. You can copy, move, or back up a .GhostVM bundle to another Mac and it will work as-is (same architecture required).

Custom Icons

Each VM can have a custom icon stored as icon.png in the bundle root. The icon is shown in the VM list and in the Dock when the VM is running. You can set the icon from the Edit VM dialog in the GUI.

CLI ReferenceSnapshots