# How Container Integrates with Apple's Virtualization Framework: Architecture and Implementation

> Discover how the apple/container project uses Apple's Virtualization framework to run Linux containers in lightweight VMs, leveraging hardware isolation and nested virtualization.

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

---

**Apple's open-source `container` project runs Linux containers inside dedicated lightweight virtual machines by leveraging the macOS Virtualization framework for hardware isolation, nested virtualization support, and device emulation.**

The `apple/container` repository provides a unique approach to containerization by using the Virtualization framework as its execution backbone. Instead of relying on kernel namespaces and cgroups, this runtime integrates with Apple's native hypervisor to spawn isolated VMs for each container workload, delivering true hardware-level separation on Apple Silicon systems.

## Pre-flight Capability Checks

Before constructing any virtual machines, the runtime validates host capabilities through [`Sources/ContainerCommands/Machine/MachineCapabilities.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Machine/MachineCapabilities.swift). This ensures the system supports nested virtualization, which is required for running containers inside VMs on Apple Silicon.

The code checks `VZGenericPlatformConfiguration.isNestedVirtualizationSupported` to verify compatibility with Apple Silicon M3+ chips running macOS 15 or later:

```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 prerequisite check prevents runtime failures by validating hardware support before attempting VM instantiation.

## VM Construction and Runtime Configuration

Once capability checks pass, [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) orchestrates the virtual machine construction process. The service initializes a `VZVirtualMachineManager` with the Linux kernel, initial filesystem mount, optional Rosetta support for x86 translation, and a logging interface:

```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, creating the actual `VZVirtualMachine` instance that powers the container.

### Filesystem Runtime Options

The integration extends to filesystem configuration through runtime options mapping. The `Filesystem` type (defined in [`Sources/ContainerResource/Container/Filesystem.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/Filesystem.swift)) translates container-specific cache and synchronization modes into Virtualization framework parameters using `vzRuntimeOptionKey` constants. In [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift), these options are formatted as key-value pairs and passed as launch arguments:

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

```

These settings control VM behavior regarding write caching and host-guest synchronization, mapped directly to the underlying Virtualization framework's configuration keys.

## Network Plumbing with vmnet

Network connectivity bridges the `vmnet` framework with Virtualization framework devices. The [`Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift) file handles the translation between macOS network attachments and VM-compatible interfaces.

The strategy deserializes network references using `vmnet_network_create_with_serialization`, then constructs a `NATNetworkInterface` that the virtual machine can utilize:

```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 approach allows containers to maintain network isolation while communicating through the host's networking stack via NAT.

## Container Lifecycle Management

After VM instantiation, the runtime creates a `LinuxContainer` instance that plugs into the running `VZVirtualMachine`. This architecture mediates all container operations—including process execution, I/O stream handling, and signal management—through the virtual machine manager.

The lifecycle follows a strict hierarchy: the Virtualization framework provides the isolated execution environment, while the container runtime orchestrates Linux-specific semantics on top. When users execute commands or terminate containers, these requests traverse through the VM manager to the underlying `VZVirtualMachine` instance, ensuring consistent state management across the host-container boundary.

## Summary

- **Hardware validation** occurs first via `MachineCapabilities.requireNestedVirtualizationSupported()`, ensuring Apple Silicon M3+ and macOS 15+ compatibility.
- **VM instantiation** relies on `VZVirtualMachineManager` in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift), configured with kernel images, filesystem mounts, and Rosetta support.
- **Filesystem optimization** maps container cache/sync modes to Virtualization framework runtime options using `vzRuntimeOptionKey` parameters.
- **Network integration** bridges `vmnet` frameworks with `NATNetworkInterface` instances through [`NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/NonisolatedInterfaceStrategy.swift).
- **Isolation guarantee** comes from running each container in its own `VZVirtualMachine`, managed by the Virtualization framework's native APIs.

## Frequently Asked Questions

### What hardware requirements exist for running containers with this Virtualization framework integration?

The integration requires Apple Silicon M3 or later processors running macOS 15 or newer. This requirement stems from the need for nested virtualization support, which the code verifies through `VZGenericPlatformConfiguration.isNestedVirtualizationSupported` before attempting VM creation.

### How does the container runtime handle filesystem performance tuning?

The runtime exposes cache and synchronization modes through the `Filesystem` type, which translates container configuration into Virtualization framework-specific keys. These settings are passed as runtime options to the VM manager, allowing fine-grained control over write caching and host-guest sync behavior without manual hypervisor configuration.

### What is the relationship between `vmnet` and the Virtualization framework in this architecture?

While the Virtualization framework provides the actual network devices inside the VM, `vmnet` handles the host-side network creation and serialization. [`NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/NonisolatedInterfaceStrategy.swift) bridges these worlds by deserializing `vmnet` network references and wrapping them in `NATNetworkInterface` objects that the Virtualization framework can attach to the guest VM.

### Does each container truly run in its own virtual machine?

Yes. According to the implementation in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift), each container receives its own `VZVirtualMachineManager` and corresponding `VZVirtualMachine` instance. This design provides hardware-level isolation between containers, contrasting with traditional Linux container runtimes that share the host kernel.