How to Expose Virtualization Capabilities to Containers in Apple Container

Pass the --virtualization flag to container run or container create to expose host virtualization devices to the guest Linux VM, enabling nested virtualization workloads when running on Apple Silicon M3 or newer.

The apple/container tool runs containers inside lightweight Linux VMs using macOS's Virtualization and vmnet frameworks. By default, these VMs cannot access hardware-assisted virtualization, but you can expose virtualization capabilities to containers by enabling a specific configuration flag that propagates through the runtime to the underlying hypervisor.

Configuration Architecture

The virtualization exposure mechanism relies on a Boolean flag that travels from the command-line interface through the configuration layer to the low-level VM runtime.

Container Configuration Structure

In Sources/ContainerResource/Container/ContainerConfiguration.swift, the ContainerConfiguration struct defines a virtualization property that controls whether the guest VM receives access to host virtualization devices. This Boolean flag is encoded and decoded from the container's JSON/YAML manifest at lines 49-50, serving as the authoritative source for the runtime's nested virtualization behavior.

CLI Flag Definition

The command-line interface exposes this capability through the --virtualization option. In Sources/Services/ContainerAPIService/Client/Flags.swift (lines 343-345), the flag is documented as "Expose virtualization capabilities to the container (requires host and guest support)". This option is available for both container run and container create commands, allowing users to specify virtualization requirements at container creation time.

Runtime Propagation

When the container manager constructs the VM configuration, the flag value propagates from the high-level configuration into the low-level hypervisor settings.

In Sources/Services/RuntimeLinux/Server/RuntimeService.swift at line 993, the implementation assigns the configuration value directly to the VM configuration: czConfig.virtualization = config.virtualization. This assignment passes the request to Apple's Virtualization framework, which then determines whether to forward virtualization-related capabilities (such as KVM device access) to the guest VM based on host hardware capabilities.

Platform Requirements and Validation

Enabling nested virtualization imposes specific hardware and software constraints that the runtime validates before VM initialization.

Hardware Prerequisites

Nested virtualization requires Apple Silicon M3 or newer Macs. The host must support the underlying virtualization extensions that macOS exposes through the Virtualization framework. If the host hardware lacks this support, the runtime returns an explicit error before attempting to boot the VM.

Error Handling

When the --virtualization flag is used on unsupported hardware, the container runtime returns the following error as documented in docs/how-to.md (lines 525-529):

Error: unsupported: "nested virtualization is not supported on the platform"

This validation occurs early in the container lifecycle, preventing the allocation of resources for workloads that cannot execute.

Kernel Verification

After successfully launching a container with virtualization enabled, verify availability inside the guest by checking for KVM driver detection:

dmesg | grep kvm

Expected output on supported systems includes references to nested virtualization support:

[    0.000000] kvm: nested=1
[    0.123456] kvm: hv_evtchn: using host event channel

The guest Linux kernel must include the appropriate virtualization options enabled, as detailed in docs/how-to.md (lines 518-520).

Usage Examples

The following examples demonstrate correct usage patterns for exposing virtualization capabilities in supported environments.

Basic Nested Virtualization

To expose virtualization capabilities to a new container, include the --virtualization flag along with a kernel that supports KVM:

container run \
    --name my-nested-vm \
    --virtualization \
    --kernel /path/to/linux-kernel-with-kvm-support \
    ubuntu:latest \
    sh -c "dmesg | grep kvm"

This command requests that the Virtualization framework expose the host's virtualization device to the guest, allowing the container to run its own VM-based workloads.

Handling Unsupported Platforms

When running on incompatible hardware, the command fails fast with a descriptive error:

container run \
    --name test \
    --virtualization \
    ubuntu:latest \
    sh -c "echo hello"

Output:

Error: unsupported: "nested virtualization is not supported on the platform"

Summary

• Configuration flag: The virtualization Boolean in ContainerConfiguration.swift controls exposure of host virtualization devices.
• CLI interface: Use --virtualization with container run or container create to request nested virtualization.
• Runtime propagation: The flag passes through RuntimeService.swift to czConfig.virtualization, which configures the Apple Virtualization framework.
• Hardware requirements: Requires Apple Silicon M3 or newer; unsupported hardware produces explicit error messages.
• Verification: Check dmesg | grep kvm inside the container to confirm KVM driver detection.

Frequently Asked Questions

What hardware is required to expose virtualization capabilities to containers?

Nested virtualization requires an Apple Silicon M3 chip or newer. The host must support the virtualization extensions that macOS exposes through the Virtualization framework. Older Apple Silicon chips or Intel-based Macs do not support this feature, and attempting to use the --virtualization flag on these platforms results in an "unsupported" error before the container boots.

How does the --virtualization flag propagate from the command line to the VM?

The flag flows through three architectural layers: first, it is parsed in Flags.swift and stored in the client configuration; second, it is serialized into the ContainerConfiguration struct in ContainerConfiguration.swift; third, it is copied to czConfig.virtualization in RuntimeService.swift at line 993, where the Apple Virtualization framework receives the request to expose host virtualization devices to the guest Linux VM.

How can I verify that virtualization is working inside the container?

After starting a container with the --virtualization flag, run dmesg | grep kvm inside the container. If the host supports nested virtualization and the guest kernel includes the appropriate drivers, you will see output indicating KVM detection, such as kvm: nested=1. Absence of this output suggests either unsupported hardware or a guest kernel lacking virtualization modules.

Can I use the --virtualization flag with any container image?

Yes, the flag works with any container image, but the guest must include a Linux kernel with KVM support enabled to utilize the exposed virtualization capabilities. The kernel must be built with the appropriate virtualization configuration options, as documented in the how-to.md guide at lines 518-520. Without a compatible kernel, the container runs but cannot instantiate nested VMs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}