Apple Container Architecture: A Deep Dive into macOS Container Virtualization

Apple Container implements a layered XPC-based architecture that runs OCI-compatible containers inside per-container lightweight Linux VMs using the macOS Virtualization framework and vmnet networking.

Apple Container is an open-source container runtime available in the apple/container repository, designed specifically for macOS. The Apple Container architecture implements a unique approach that combines native frameworks with lightweight virtualization, isolating each container in its own minimal Linux VM. This design leverages XPC services and the macOS Virtualization framework to provide OCI-compatible containerization with enhanced security boundaries.

Core Architectural Layers

Command-Line Interface (CLI)

The container binary serves as the primary entry point, parsing user commands and communicating with backend services. It handles standard operations like run, exec, and network inspect by making XPC calls to the container-apiserver daemon.

Launch Agent and API Server

The container-apiserver acts as the central orchestrator, registered with launchd via container system start. Written in Swift, this component exposes GRPC-style APIs for container, image, and network management. It coordinates between the CLI and the various XPC helper services, maintaining the overall system state.

XPC Helper Services

The architecture delegates specialized tasks to three distinct XPC services, each running in its own sandbox:

• container-core-images: Manages image storage and registry access, utilizing the macOS Keychain for credential storage.
• container-network-vmnet: Configures virtual networking through the vmnet framework, providing NAT-style networking on the 192.168.64.0/24 subnet by default.
• container-runtime-linux: Handles per-container runtime operations inside lightweight VMs, as implemented in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift.

The XPC communication layer is centralized in Sources/ContainerXPC/XPCServerSession.swift, which provides the foundational session handling used by all helpers.

Virtualization Layer

Each container runs inside a minimal Linux VM created via the macOS Virtualization framework. This VM isolates the container's kernel, networking stack, and filesystem while sharing only explicitly mounted host paths. The implementation in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift configures these VMs with minimal footprints for fast startup times.

Networking and Security

The vmnet framework (available in macOS 15+) provides virtual Ethernet interfaces for each VM. macOS 15 offers limited isolation, while macOS 26+ supports full VMnet-based networks. Security is enforced through XPC sandboxing, VM-level isolation, and minimal runtime libraries, ensuring that only user-mounted files are visible inside the container. System logging integrates with Unified Logging via Sources/ContainerLog/ServiceLogger.swift.

Data Flow and Component Interaction

When a user executes container run, the system follows this execution path:

1. The CLI contacts container-apiserver via XPC.
2. The API server creates an XPC client for container-runtime-linux.
3. The runtime helper requests the Virtualization framework to launch a Linux VM.
4. The VM's network interface attaches to container-network-vmnet (vmnet).
5. container-core-images fetches layers using Keychain-stored credentials and streams them into the VM.
6. The container's init process executes, with stdout/stderr routed back through XPC helpers to the CLI.

Configuration and System Defaults

System-wide settings are managed by the ContainerSystemConfig Swift struct, defined in Sources/ContainerPersistence/ContainerSystemConfig.swift. This configuration includes VM kernel paths, memory limits, networking defaults, and DNS settings, read from a TOML file at startup. The modular design allows independent updates to helpers without affecting the core system.

Implementation Examples

Starting a Container via Swift Client

import ContainerAPIClient
import ContainerRuntimeClient
import ContainerXPC

let client = try ContainerAPIClient()
let spec = ContainerSpec(
    image: "docker.io/library/alpine:latest",
    command: ["/bin/sh", "-c", "echo Hello from container"]
)

let containerID = try client.runContainer(spec: spec)
let stream = try client.attach(to: containerID, stdOut: true, stdErr: true)
for try await line in stream.lines {
    print(line)
}

The client library is generated from XPC service definitions in Sources/ContainerAPIService/Server/Containers/ContainersService.swift.

XPC Server Implementation Pattern

import ContainerXPC
import ContainerRuntimeLinuxServer

class RuntimeServer: NSObject, ContainerRuntimeLinuxServerProtocol {
    func startContainer(_ request: StartRequest,
                       withReply reply: @escaping (StartResponse) -> Void) {
        let vm = LightweightLinuxVM(configuration: request.vmConfig)
        vm.start()
        reply(StartResponse(success: true))
    }
}

let listener = XPCListener(serviceName: "com.apple.container.runtime.linux")
listener.delegate = RuntimeServer()
listener.resume()

This pattern mirrors the actual implementation in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift.

Inspecting Network Configuration

$ container network inspect
{
  "subnet": "192.168.64.0/24",
  "gateway": "192.168.64.1",
  "driver": "vmnet"
}

The CLI forwards this request to the container-network-vmnet XPC helper, which queries the vmnet framework directly.

Summary

• Apple Container uses a layered XPC architecture with specialized helpers for images, networking, and runtime operations.
• Each container runs in an isolated Linux VM via the macOS Virtualization framework, providing enhanced security over traditional containerization.
• The container-apiserver coordinates between the CLI and XPC services, while container-runtime-linux manages VM lifecycle in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift.
• Networking relies on the vmnet framework, defaulting to the 192.168.64.0/24 subnet.
• Configuration is centralized in ContainerSystemConfig within Sources/ContainerPersistence/ContainerSystemConfig.swift.

Frequently Asked Questions

How does Apple Container differ from Docker Desktop on macOS?

While Docker Desktop uses a single Linux VM to host all containers, Apple Container creates a separate lightweight VM for each container via the Virtualization framework. This provides stronger isolation at the VM level, though with different resource characteristics. The architecture relies on XPC services rather than a monolithic daemon.

What is the role of the container-apiserver component?

The container-apiserver is the central launch agent that registers with launchd and exposes GRPC-style APIs for container management. It acts as the intermediary between the CLI and the specialized XPC helpers, coordinating image pulls, network setup, and VM lifecycle operations.

Where is the network configuration stored in the source code?

Network configuration defaults are defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, while the actual vmnet integration is implemented in the container-network-vmnet XPC helper. The system uses the vmnet framework to create virtual Ethernet interfaces, with the default subnet 192.168.64.0/24 specified in the technical documentation.

Can Apple Container run on Intel Macs or only Apple Silicon?

The architecture relies on the macOS Virtualization framework, which has different capabilities across hardware generations and macOS versions. While the source code in Sources/Plugins/RuntimeLinux/ handles VM configuration generically, specific virtualization features depend on the underlying macOS support for the host hardware.

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