# How Container Integrates with the macOS Virtualization Framework: Architecture and Implementation

> Discover how container leverages the macOS Virtualization framework for secure, isolated Linux VMs. Explore architecture and implementation details for Apple Silicon.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: architecture
- Published: 2026-07-08

---

**Container uses the macOS Virtualization framework to run each Linux container inside its own lightweight virtual machine, leveraging nested virtualization support on Apple Silicon M3+ and macOS 15+ for secure, isolated execution.**

The `container` project by Apple enables Linux container workloads on macOS by building directly atop Apple's native **Virtualization** framework. Rather than sharing the host kernel like traditional container runtimes, this architecture encapsulates each container within a dedicated virtual machine, providing hardware-level isolation while maintaining the familiar container developer experience.

## Pre-flight Capability Checks

Before spinning up any workloads, `container` verifies that the host hardware supports the necessary virtualization features. In [`Sources/ContainerCommands/Machine/MachineCapabilities.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Machine/MachineCapabilities.swift), the system queries the Virtualization API to ensure **nested virtualization** is available.

```swift
import Virtualization

enum MachineCapabilities {
    static func requireNestedVirtualizationSupported() throws {
        guard VZGenericPlatformConfiguration.isNestedVirtualizationSupported else {
            throw ContainerizationError(
                .unsupported,
                message: "nested virtualization is not supported on this host (requires Apple Silicon M3+ and macOS 15+)"
            )
        }
    }
}

```

This check is mandatory on Apple Silicon M3+ devices running macOS 15+, as the framework requires nested virtualization support to run Linux containers efficiently within the host OS.

## VM Construction and Management

Once capabilities are verified, [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) constructs the virtual machine infrastructure. The service initializes a `VZVirtualMachineManager` with the Linux kernel, initial filesystem mounts, and optional **Rosetta** support for x86_64 binary translation.

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

```

This manager serves as the primary interface to the Virtualization framework, instantiating the `VZVirtualMachine` that powers the container. According to the source code at lines 165–170, this approach allows `container` to treat each Linux container as a discrete VM with dedicated resources.

## Runtime Configuration and Filesystem Optimization

Container performance depends heavily on how the VM handles filesystem caching and synchronization. The `Filesystem` type maps container-specific settings to Virtualization framework runtime keys, passing these as launch arguments to optimize I/O behavior.

In [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 1364–1376), the system translates cache modes and sync settings into Virtualization-specific keys:

```swift
let cacheOption = "\(Filesystem.CacheMode.vzRuntimeOptionKey)=\(cacheMode.asVZRuntimeOption)"
let syncOption  = "\(Filesystem.SyncMode.vzRuntimeOptionKey)=\(syncMode.asVZRuntimeOption)"

```

These options control memory ballooning, cache behavior, and sync modes, allowing developers to tune storage performance for their specific workloads without modifying the underlying VM configuration directly.

## Network Plumbing and Interface Strategy

While the Virtualization framework provides the VM compute layer, networking requires integration with the `vmnet` framework. [`Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift) bridges these two systems by translating network attachments into Virtualization-compatible interfaces.

The strategy deserializes network references using `vmnet_network_create_with_serialization`, then wraps them in a `NATNetworkInterface` that the `VZVirtualMachine` can consume:

```swift
let networkRef = vmnet_network_create_with_serialization(additionalData.underlying, &status)
return NATNetworkInterface(
    ipv4Address: attachment.ipv4Address,
    ipv4Gateway: interfaceIndex == 0 ? attachment.ipv4Gateway : nil,
    reference: networkRef,
    macAddress: attachment.macAddress,
    mtu: attachment.mtu ?? 1280
)

```

This abstraction allows containers to maintain consistent network identities while leveraging the host's NAT capabilities through the Virtualization framework's device emulation.

## Container Lifecycle Management

Once the `VZVirtualMachine` is running, `container` creates a `LinuxContainer` instance that plugs into the VM. This object manages the container's processes, I/O streams, and boot logs, mediating all interactions—start, stop, and exec—through the VM manager.

The Virtualization framework handles **isolated execution**, **resource control**, and **device emulation**, while `container` adds the orchestration layer for container-specific semantics like image unpacking and OCI runtime compatibility.

## Summary

- **Hardware Requirements**: The integration requires Apple Silicon M3+ and macOS 15+ for nested virtualization support, verified via `VZGenericPlatformConfiguration.isNestedVirtualizationSupported`.
- **VM Architecture**: Each container runs in its own `VZVirtualMachine` managed by `VZVirtualMachineManager`, constructed in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift).
- **Performance Tuning**: Filesystem cache and sync modes map to Virtualization runtime keys for optimized storage I/O.
- **Network Bridging**: The `NonisolatedInterfaceStrategy` converts `vmnet` references into `NATNetworkInterface` objects compatible with the Virtualization framework.
- **Security Model**: Hardware-level isolation through dedicated VMs provides stronger security boundaries than traditional kernel-sharing container runtimes.

## Frequently Asked Questions

### Does container require specific hardware to integrate with the macOS Virtualization framework?

Yes. According to the source code in [`MachineCapabilities.swift`](https://github.com/apple/container/blob/main/MachineCapabilities.swift), the integration requires Apple Silicon M3 or later and macOS 15 or newer. This hardware configuration supports nested virtualization via `VZGenericPlatformConfiguration.isNestedVirtualizationSupported`, which is mandatory for running Linux containers within the Virtualization framework's VM layer.

### How does container handle networking when using the Virtualization framework?

Container bridges the `vmnet` framework with the Virtualization framework through [`NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/NonisolatedInterfaceStrategy.swift). This component deserializes network attachments using `vmnet_network_create_with_serialization` and wraps them in `NATNetworkInterface` objects that the `VZVirtualMachine` can use, providing NAT-based connectivity while maintaining MAC address and MTU configuration.

### What performance benefits does the Virtualization framework provide for container workloads?

The Virtualization framework enables **memory ballooning** and **dedicated resource allocation** for each container VM. By mapping filesystem cache modes and sync settings to Virtualization runtime keys (as seen in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) lines 1364–1376), containers achieve optimized I/O throughput without competing for host kernel resources, resulting in more predictable performance for storage-intensive workloads.

### Can I run x86_64 Linux containers on Apple Silicon using this Virtualization framework integration?

Yes. The `RuntimeService` accepts an optional `rosetta` parameter when constructing the `VZVirtualMachineManager`. When enabled, this leverages Apple's Rosetta translation technology within the Virtualization framework to run x86_64 Linux binaries inside the ARM-based virtual machine, providing seamless multi-architecture support.