# How Apple's Container Runtime Uses the Virtualization Framework: A Deep Dive into the Implementation

> Discover how Apple's container runtime leverages the Virtualization framework for hardware-accelerated isolation and native networking in macOS-hosted Linux containers. Learn the implementation details.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: deep-dive
- Published: 2026-06-18

---

**Apple's container runtime creates a lightweight macOS-hosted virtual machine for each Linux container using the Virtualization framework (`VZVirtualMachineManager`) and the vmnet subsystem, providing hardware-accelerated isolation with native networking support.**

The `apple/container` repository implements a Linux container runtime that leverages macOS native virtualization capabilities. Unlike traditional container runtimes that rely on shared kernel architectures, this implementation uses the **Virtualization framework** to spawn isolated virtual machines for each container, ensuring secure sandboxing while maintaining performance through hardware acceleration. The runtime is defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) with a direct dependency on Apple's Virtualization framework.

## VM Construction with VZVirtualMachineManager

In [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift), the runtime instantiates a `VZVirtualMachineManager` to manage the VM lifecycle. This manager abstracts the low-level `VZVirtualMachine` object and provides a Swift-friendly API for booting, stopping, and pausing containers.

The manager is initialized with the container's kernel image, root filesystem, optional Rosetta support for x86_64 translation, and a logger:

```swift
let vmm = VZVirtualMachineManager(
    kernel: kernel,
    initialFilesystem: bundle.initialFilesystem.asMount,
    rosetta: config.rosetta,
    logger: self.log
)

```

This setup ensures that each container runs inside its own hardware-accelerated VM rather than sharing the host kernel.

## Linux Container Configuration

The **LinuxContainer** class receives the `VZVirtualMachineManager` instance and a configuration struct defining CPU, memory, sysctls, mounts, and network interfaces. In [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift), the runtime configures these parameters before launching the container:

```swift
let container = try LinuxContainer(id, rootfs: rootfs, vmm: vmm, logger: self.log) { czConfig in
    try Self.configureContainer(czConfig: &czConfig, config: config, dynamicEnv: dynamicEnv, log: self.log)
    czConfig.interfaces = interfaces
    // Additional configuration...
}

```

This architecture binds the container's processes to the specific VM instance created by the Virtualization framework.

## Network Interface Strategies

The runtime supports two distinct networking models through the Virtualization framework, implemented in separate strategy files.

### Non-Isolated Interfaces with vmnet

For macOS 26+ custom networks, [`Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift) imports both `Virtualization` and `vmnet` frameworks. It deserializes a vmnet network reference using `vmnet_network_create_with_serialization` and attaches it to the VM:

```swift
import Virtualization
import vmnet

guard let networkRef = vmnet_network_create_with_serialization(
    additionalData.underlying,
    &status
) else {
    throw ContainerizationError(.invalidState, message: "cannot deserialize custom network")
}
let iface = NATNetworkInterface(
    ipv4Address: attachment.ipv4Address,
    ipv4Gateway: ifaceIdx == 0 ? attachment.ipv4Gateway : nil,
    reference: networkRef,
    macAddress: attachment.macAddress,
    mtu: attachment.mtu ?? 1280
)

```

### Isolated NAT Interfaces

The default isolated strategy creates a `VZBridgedNetworkDevice` or `VZNetworkDevice` backed by the system's NAT stack, providing network isolation without requiring custom network plugins.

## Filesystem Integration and Caching

When mounting block devices or volumes, the `Filesystem` class in [`Sources/ContainerResource/Container/Filesystem.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/Filesystem.swift) defaults the cache mode to `.on` to address a known Linux filesystem bug when running under Virtualization:

```swift
public static func block(
    format: String,
    source: String,
    destination: String,
    options: MountOptions,
    cache: CacheMode = .on,        // default fixes Linux FS issue when using Virtualization
    sync: SyncMode = .fsync
) -> Filesystem { 
    // Implementation...
}

```

This direct interaction with the Virtualization-backed storage stack ensures data consistency.

## Summary

- **VM per container**: Each Linux container runs in its own isolated virtual machine created via `VZVirtualMachineManager`
- **Hardware acceleration**: The Virtualization framework provides native CPU, memory, and storage virtualization with minimal overhead
- **Flexible networking**: Supports both non-isolated custom networks (via vmnet) and isolated NAT interfaces
- **Storage optimization**: Default filesystem caching works around Linux-in-Virtualization bugs
- **Lifecycle management**: All VM operations (boot, shutdown, snapshots) are mediated through the manager abstraction

## Frequently Asked Questions

### Does each container run in its own VM?

Yes. According to the `apple/container` source code, the runtime creates a dedicated `VZVirtualMachine` for each container through the `VZVirtualMachineManager` abstraction. This provides true hardware-level isolation rather than the process-level isolation found in traditional Linux containers.

### What macOS version is required for custom network plugins?

Non-isolated network interfaces using `vmnet_network_create_with_serialization` require macOS 26 (or later) and the custom network plugin infrastructure. This allows containers to integrate with existing network topologies while maintaining VM-level isolation.

### How does the runtime handle x86_64 containers on Apple Silicon?

The runtime supports optional **Rosetta** translation when configuring the VM. The `VZVirtualMachineManager` accepts a `rosetta` parameter during initialization, enabling x86_64 Linux binaries to run inside the Virtualization framework-backed VM on Apple Silicon Macs.

### Why is filesystem caching set to "on" by default?

When running Linux under the Virtualization framework, certain filesystem operations exhibit specific behaviors that require aggressive caching. The [`Filesystem.swift`](https://github.com/apple/container/blob/main/Filesystem.swift) implementation defaults to `CacheMode.on` to work around these Linux-in-Virtualization bugs, ensuring stable block device and volume mounts.