How to Configure the Graphics Device for the vphone‑cli VM

The graphics device for a vphone‑cli VM is configured via CLI flags that populate a VZMacGraphicsDeviceConfiguration with a custom VZMacGraphicsDisplayConfiguration before the VM boots.

vphone‑cli is a command‑line tool that wraps Apple's Virtualization.framework to run macOS virtual machines. The virtual display's resolution, pixel density, and rendering pipeline are all controlled through specific command‑line options parsed at launch and applied during VZVirtualMachineConfiguration construction.

Graphics Configuration Architecture

The graphics subsystem in vphone‑cli follows a three‑layer architecture:

• CLI layer (VPhoneCLI.swift) — parses user flags
• Options layer (VPhoneVirtualMachine.Options) — stores validated values
• Configuration layer (VPhoneVirtualMachine.swift) — builds the VZMacGraphicsDeviceConfiguration

This separation ensures that display settings are validated before the VM is instantiated.

Setting Resolution and Pixel Density via CLI Flags

vphone‑cli exposes three primary flags to configure the graphics device. These are defined in sources/vphone-cli/VPhoneCLI.swift and map directly to VZMacGraphicsDisplayConfiguration parameters:

Flag	Purpose	Default
--screen-width	Horizontal pixels (widthInPixels)	1920
--screen-height	Vertical pixels (heightInPixels)	1080
--screen-ppi	Display density (pixelsPerInch)	220

Launch a VM with custom graphics settings:

vphone-cli boot --screen-width 2560 --screen-height 1440 --screen-ppi 300

For a 4K display configuration:

vphone-cli boot \
    --screen-width 3840 \
    --screen-height 2160 \
    --screen-ppi 300

How the Graphics Device Is Constructed

In sources/vphone-cli/VPhoneVirtualMachine.swift, the graphics configuration is assembled during VM setup and attached to the VZVirtualMachineConfiguration:

let gfx = VZMacGraphicsDeviceConfiguration()
gfx.displays = [
    VZMacGraphicsDisplayConfiguration(
        widthInPixels:   options.screenWidth,
        heightInPixels:  options.screenHeight,
        pixelsPerInch:   options.screenPPI
    ),
]
config.graphicsDevices = [gfx]

The VZMacGraphicsDeviceConfiguration tells Virtualization.framework to expose a macOS‑style GPU to the guest. The single VZMacGraphicsDisplayConfiguration in its displays array defines the virtual monitor's properties.

Accessing the Graphics Display at Runtime

The configured display surface is accessible through private APIs for screenshotting and screen recording. In sources/vphone-cli/VPhoneVirtualMachineView.swift, the recordingGraphicsDisplay property exposes the underlying VZGraphicsDisplay:

// Accessing the graphics display for capture
if let display = vmView.recordingGraphicsDisplay {
    // Capture frame via VZGraphicsDisplay APIs
}

This same display reference is used by VPhoneScreenRecorder.swift to encode video frames from the VM output.

Advanced: GPU Accelerator Devices

vphone‑cli automatically injects additional graphics accelerators when private APIs are available. The following block in VPhoneVirtualMachine.swift loads VideoToolbox, Neural Engine, and scaler accelerators:

if let obj1 = Dynamic._VZMacVideoToolboxDeviceConfiguration().asObject,
   let obj2 = Dynamic._VZMacNeuralEngineDeviceConfiguration().asObject,
   let obj3 = Dynamic._VZMacScalerAcceleratorDeviceConfiguration().asObject {
    Dynamic(config)._setAcceleratorDevices([obj1, obj2, obj3])
}

These accelerators are transparent to users and require no manual configuration.

Stand‑alone Configuration Example

To manually build a graphics configuration for testing or custom tooling:

let vmConfig = VZVirtualMachineConfiguration()
let graphics = VZMacGraphicsDeviceConfiguration()
graphics.displays = [
    VZMacGraphicsDisplayConfiguration(
        widthInPixels: 1280,
        heightInPixels: 800,
        pixelsPerInch: 163
    )
]
vmConfig.graphicsDevices = [graphics]

Key Source Files

Understanding these files provides complete visibility into the graphics pipeline:

• sources/vphone-cli/VPhoneCLI.swift — CLI flag definitions and parsing
• sources/vphone-cli/VPhoneVirtualMachine.swift — graphics device assembly
• sources/vphone-cli/VPhoneVirtualMachineView.swift — display surface access
• sources/vphone-cli/VPhoneScreenRecorder.swift — frame capture implementation

Summary

• Pass --screen-width, --screen-height, and --screen-ppi to configure the virtual display at launch
• VZMacGraphicsDeviceConfiguration is the core Apple framework class used by vphone‑cli
• Graphics settings are applied in VPhoneVirtualMachine.swift before the VM boots
• GPU accelerators are auto‑injected when private APIs are available
• Runtime access to the display surface enables screenshotting and recording

Frequently Asked Questions

What graphics API does vphone‑cli use under the hood?

vphone‑cli uses Apple's Virtualization.framework, specifically VZMacGraphicsDeviceConfiguration and VZMacGraphicsDisplayConfiguration to expose a virtual GPU and display to the guest macOS system.

Can I set a custom DPI or scale factor for Retina‑sharp rendering?

Yes. The --screen-ppi flag controls pixel density. Higher values (e.g., 220–300) produce sharper UI at the same resolution. This maps directly to pixelsPerInch in the VZMacGraphicsDisplayConfiguration.

Is external GPU or discrete GPU passthrough supported?

No. vphone‑cli configures the graphics device entirely through VZMacGraphicsDeviceConfiguration, which provides a virtualized macOS GPU. Hardware GPU passthrough is not implemented in the current codebase.

Where does vphone‑cli store the graphics configuration?

The graphics configuration is ephemeral—it is rebuilt from CLI flags on every launch in VPhoneVirtualMachine.swift. No persistent configuration file stores display settings; pass flags each time or wrap vphone-cli in a shell alias or script.

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