# Apple Container Architecture: A Deep Dive into macOS Container Virtualization

> Explore Apple Container architecture, a layered XPC-based system for OCI-compatible containers within macOS lightweight Linux VMs via the Virtualization framework.

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

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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

```swift
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`](https://github.com/apple/container/blob/main/Sources/ContainerAPIService/Server/Containers/ContainersService.swift).

### XPC Server Implementation Pattern

```swift
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

```bash
$ 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.