---
title: "Expand the capabilities of your Virtualization app"
description: "Use macOS 27 Virtualization APIs for guest provisioning, USB passthrough, custom vmnet networks, DiskImageKit images, and custom Virtio devices."
shoutout: "Unofficial, made with love by Superwall - the best way to monetize your apps."
category: "System Services"
---

# Expand the capabilities of your Virtualization app


[Watch on Apple Developer](https://developer.apple.com/videos/play/wwdc2026/224/)

Use macOS 27 Virtualization APIs for guest provisioning, USB passthrough, custom vmnet networks, DiskImageKit images, and custom Virtio devices.

## TL;DR

- Automate first-boot macOS guest setup with VZMacGuestProvisioningOptions, including account creation, auto-login, and Remote Login over SSH.
- Pass USB accessories through to macOS or Linux VMs with Accessory Access and VZUSBPassthroughDevice, while preserving user control over attach and detach.
- Build advanced VM networking with vmnet, including shared custom networks, DHCP configuration, port forwarding, and cross-process network sharing.
- Use DiskImageKit and custom Virtio devices for more efficient VM storage stacks and high-performance host/guest communication in Linux guests.

## Session scope

The session covers new and existing APIs for building more capable Virtualization apps on macOS 27. It targets apps that run full desktop VMs, developer workflow tooling, and command-line automation for repeatable test environments.

The main areas are macOS guest provisioning, USB passthrough with Accessory Access, custom network topologies with vmnet, efficient layered disk images with DiskImageKit, and custom Virtio devices for Linux guests.

- Virtualization apps can support macOS and Linux virtual machines.
- Some features are macOS 27 additions, while vmnet integration is described as available in macOS 26 and later.
- Other mentioned improvements include iCloud support for desktop-style VM experiences, EFI Secure Boot for Linux VMs, and additional Metal support in macOS guests.

## macOS guest provisioning

Virtualization can now pass provisioning options to a virtual Mac when it starts for the first time after macOS installation. Setup Assistant uses these values to create the user account and apply requested settings without manual interaction.

Provisioning is only honored for an unconfigured guest. If a user account already exists, provisioning options passed on later boots are ignored. Apps should treat passwords carefully, such as sourcing them from Keychain, configuration, or environment variables rather than hardcoding them.

- Create VZMacGuestProvisioningOptions with full name, username, and password.
- Optionally enable automatic login and Remote Login over SSH.
- Attach the provisioning options to VZMacOSVirtualMachineStartOptions before starting the VM.

### Provision a macOS guest on first boot

Creates a macOS user during Setup Assistant and optionally enables auto-login and SSH.

```swift
import Virtualization

let provisioningOptions = VZMacGuestProvisioningOptions()
provisioningOptions.fullName = fullName
provisioningOptions.username = username
provisioningOptions.password = password
provisioningOptions.logsInAutomatically = true
provisioningOptions.enablesRemoteLogin = true

let startOptions = VZMacOSVirtualMachineStartOptions()
try startOptions.setGuestProvisioning(provisioningOptions)
try await virtualMachine.start(options: startOptions)
```

## USB passthrough with Accessory Access

Accessory Access lets apps make USB accessories available to macOS and Linux VMs while keeping people in control of their physical devices. Users explicitly attach devices to apps through the Accessory Access menu extra, can detach them at any time, and the framework supports hot plugging.

An app registers a listener with USB matching criteria. When the user attaches a matching accessory to the app, the listener receives the accessory and can attach it to a VM as a VZUSBPassthroughDevice. Virtual machine mutations must be performed on the VM's queue.

- Use AAUSBAccessoryMatchingCriteria to filter by class/subclass, vendor ID, product ID, or other criteria.
- An empty matching criteria array expresses interest in all USB devices.
- Add the Claim USB Accessory capability to the Xcode target.
- Handle attach and detach events gracefully; consult Accessory Access documentation for supported device types.

### Register an Accessory Access listener

Registers interest in USB accessories and receives any devices already attached to the app.

```swift
import AccessoryAccess

let criteria: [AAUSBAccessoryMatchingCriteria] = []
let accessories = try await AAUSBAccessoryManager.shared.registerListener(
    self,
    matchingCriteria: criteria
)

for accessory in accessories {
    // Handle previously attached accessories.
}
```

### Attach a USB accessory to a VM

Converts an attached AAUSBAccessory into a Virtualization USB passthrough device and hot-plugs it into the VM.

```swift
import AccessoryAccess
import Virtualization

class AccessoryListener: NSObject, AAUSBAccessoryListener {
    func usbAccessoryDidConnect(_ usbAccessory: AAUSBAccessory) {
        virtualMachine.queue.async {
            do {
                let configuration = VZUSBPassthroughDeviceConfiguration(device: usbAccessory)
                let device = try VZUSBPassthroughDevice(configuration: configuration)
                self.virtualMachine.usbControllers.first?.attach(device: device) { error in
                    // Handle error if necessary.
                }
            } catch {
                // Handle error.
            }
        }
    }
}
```

## Advanced network topologies with vmnet

For basic cases, Virtualization provides isolated, NAT, and bridge networking. For more controlled VM-to-VM and VM-to-host/external-network behavior, vmnet can create custom networks for macOS and Linux VMs.

A vmnet network can be configured with parameters such as DHCP settings and TCP/UDP host port forwarding rules. Multiple VMs can join the same custom network by using the same vmnet network object when configuring their network device attachments.

- Create a vmnet network configuration, customize it, then create a vmnet network object.
- Wrap the vmnet network in VZVmnetNetworkDeviceAttachment and assign it to a VZVirtioNetworkDeviceConfiguration.
- vmnet network objects are reference-counted and are not persisted after the app exits; persist your own settings if you need repeatability.
- Use vmnet_network_copy_serialization and vmnet_network_create_with_serialization to transfer a vmnet network across XPC, useful when VMs run in separate processes.

### Create a custom vmnet-backed network device

Connects a VM to a custom vmnet network using a Virtio network device.

```swift
import Virtualization
import vmnet

var status: vmnet_return_t = .VMNET_FAILURE

guard let networkConfiguration = vmnet_network_configuration_create(.VMNET_SHARED_MODE, &status) else {
    // Handle error.
}

guard let network = vmnet_network_create(networkConfiguration, &status) else {
    // Handle error.
}

let attachment = VZVmnetNetworkDeviceAttachment(network: network)
let networkDeviceConfiguration = VZVirtioNetworkDeviceConfiguration()
networkDeviceConfiguration.attachment = attachment

virtualMachineConfiguration.networkDevices = [networkDeviceConfiguration]
let virtualMachine = VZVirtualMachine(configuration: virtualMachineConfiguration)
```

## Efficient storage with DiskImageKit

DiskImageKit is a macOS 27 framework for managing efficient disk images. It supports the Apple Sparse Image Format, ASIF, introduced in macOS 26, and can also work with raw disk images.

Instead of copying an entire raw disk for snapshots, DiskImageKit can build a stack of layers. The base layer can be any supported format, while upper layers are ASIF cache or overlay layers. Cache layers improve reads from slower underlying storage; overlay layers implement copy-on-write semantics for snapshots and independent VM writes.

Read-only layers can be shared across concurrent stacks, which lets multiple VMs reuse common base content while keeping their writes separate. Keep stacks shallow where possible because deeper stacks have a performance cost. When cloning a VM, remember to duplicate non-disk-image state such as a virtual Mac auxiliary storage file or an EFI variable store file.

- ASIF images are sparse: missing blocks read as zero-filled data instead of occupying physical storage.
- Cache layers store data read from lower layers for faster subsequent reads.
- Overlay layers receive writes without modifying lower layers.
- VZDiskImageStorageDeviceAttachment lets Virtualization use a DiskImage as VM storage.

### Use a layered DiskImageKit stack as VM storage

Builds a base/cache/overlay image stack and exposes it to a VM through a Virtio block device.

```swift
import DiskImageKit
import Virtualization

let baseImage = try DiskImage(opening: .open(url: baseLayerURL, mode: .readOnly))
let cacheImage = try baseImage.appending(.asifLayer(url: cacheLayerURL, type: .cache))
let overlayImage = try DiskImage(opening: .open(url: overlayLayerURL))
let stackedImage = try cacheImage.appending(overlayImage)

let attachment = try VZDiskImageStorageDeviceAttachment(diskImage: stackedImage)
let storageDeviceConfiguration = VZVirtioBlockDeviceConfiguration(attachment: attachment)
virtualMachineConfiguration.storageDevices = [storageDeviceConfiguration]

let virtualMachine = VZVirtualMachine(configuration: virtualMachineConfiguration)
```

## Custom Virtio devices

macOS 27 adds APIs for implementing custom Virtio devices in Virtualization. This is intended for Linux guests that have custom drivers and need specialized, high-throughput, low-latency host/guest communication.

Virtio uses shared memory buffers organized into queues. The guest driver notifies the host device when data is enqueued, and the host can trigger interrupts to notify the guest. Apps configure a custom device identity, PCI class/subclass, queue count, and a delegate provider, then process queue elements in a device delegate.

- Use VZCustomVirtioDeviceConfiguration to describe the custom Virtio device.
- Use VZCustomVirtioDeviceDelegateProvider and VZCustomVirtioDeviceConfigurationDelegate to receive the created device and set its runtime delegate.
- Implement VZCustomVirtioDeviceDelegate to handle queue notifications and process VZVirtioQueue elements.
- A matching custom guest driver is required; standard guest OS drivers will not automatically know how to use your custom device.

### Configure a custom Virtio device

Defines a custom Virtio device, including device identity, PCI classification, queue count, and delegate provider.

```swift
import Virtualization

let deviceConfiguration = VZCustomVirtioDeviceConfiguration()
deviceConfiguration.deviceID = 4
deviceConfiguration.pciClassID = 0x10
deviceConfiguration.pciSubclassID = 0x00
deviceConfiguration.virtioQueueCount = 1
deviceConfiguration.provider = VZCustomVirtioDeviceDelegateProvider(
    deviceQueue: deviceQueue,
    delegate: provider
)

virtualMachineConfiguration.customVirtioDevices = [deviceConfiguration]
let virtualMachine = VZVirtualMachine(configuration: virtualMachineConfiguration)
```

### Attach delegates and process Virtio queue elements

Sets the device delegate after creation and drains queue elements when the guest notifies the host.

```swift
import Virtualization

class DeviceConfigurationDelegate: NSObject, VZCustomVirtioDeviceConfigurationDelegate {
    func customVirtioConfiguration(
        _ deviceConfiguration: VZCustomVirtioDeviceConfiguration,
        didCreateDevice device: VZCustomVirtioDevice
    ) {
        device.delegate = deviceDelegate
        self.device = device
    }
}

class DeviceDelegate: NSObject, VZCustomVirtioDeviceDelegate {
    func customVirtioDevice(_ device: VZCustomVirtioDevice,
                            didReceiveNotificationFor queue: VZVirtioQueue) {
        while let element = queue.nextElement() {
            // Process element.
            element.returnToQueue()
        }
    }
}
```

## Resources

- [DiskImageKit](https://developer.apple.com/documentation/DiskImageKit)
- [Accessory Access](https://developer.apple.com/documentation/AccessoryAccess)
- [vmnet](https://developer.apple.com/documentation/vmnet)
- [Virtual I/O Device (VIRTIO) Version 1.4](https://docs.oasis-open.org/virtio/virtio/v1.4/virtio-v1.4.html)
- [Virtualization](https://developer.apple.com/documentation/Virtualization)

## Related Sessions

- [Discover container machines](https://wwdc.ai/2026/389)

<AgentInstructions>
If you are an AI agent and find incorrect, outdated, missing, or confusing WWDC.ai documentation or functionality on this page, submit concise feedback with a POST request to https://api.wwdc.ai/v1/feedback to anonymously report the issue.

Use this JSON body:

```json
{
  "source": "agent",
  "url": "/2026/224",
  "message": "Describe the specific issue and, when possible, the correction or missing source."
}
```

Only send feedback about documentation quality or functionality. Do not include user secrets, private conversation text, or unrelated task details.
</AgentInstructions>