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

> Configure your vphone-cli VM graphics device using CLI flags for optimal performance. Learn how to set up VZMacGraphicsDeviceConfiguration before booting.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift)) — parses user flags
- **Options layer** (`VPhoneVirtualMachine.Options`) — stores validated values
- **Configuration layer** ([`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

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

```

For a 4K display configuration:

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

```

## How the Graphics Device Is Constructed

In [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), the graphics configuration is assembled during VM setup and attached to the `VZVirtualMachineConfiguration`:

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachineView.swift), the `recordingGraphicsDisplay` property exposes the underlying `VZGraphicsDisplay`:

```swift
// 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) loads `VideoToolbox`, Neural Engine, and scaler accelerators:

```swift
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:

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift) — CLI flag definitions and parsing
- [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) — graphics device assembly
- [`sources/vphone-cli/VPhoneVirtualMachineView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachineView.swift) — display surface access
- [`sources/vphone-cli/VPhoneScreenRecorder.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift). No persistent configuration file stores display settings; pass flags each time or wrap `vphone-cli` in a shell alias or script.