# Main Components of the Apple Container Project: Architecture Deep Dive

> Explore the main components of the apple/container project. Discover its architecture including CLI, system daemon, XPC helpers, Containerization library, and supporting subsystems.

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

---

**The apple/container repository implements a full-stack container runtime for macOS Apple silicon, organized into a command-line interface, system daemon, three specialized XPC helpers, a low-level Containerization library, and supporting subsystems for building, networking, and persistence.**

The apple/container project provides a complete open-source container runtime specifically designed for macOS Apple silicon. Unlike traditional Linux container runtimes, this architecture leverages the macOS Virtualization and `vmnet` frameworks to execute Linux containers inside lightweight virtual machines. Understanding the main components of the apple/container project reveals a modular design with strict process isolation through XPC communication.

## Command-Line Interface (CLI)

The **`container`** binary serves as the primary user-facing entry point. This Swift-based CLI parses subcommands such as `run`, `build`, and `system start`, then communicates with the background daemon via XPC.

The build logic resides in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift), which orchestrates the `container build` command. This file implements the pipeline that parses `Containerfile` syntax and constructs OCI-compliant images. Protocol buffer definitions for the build process are located in [`Sources/ContainerBuild/Builder.pb.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.pb.swift).

## System Daemon (container-apiserver)

The **`container-apiserver`** functions as a launch agent that starts when you run `container system start`. This system daemon hosts the high-level management APIs for containers, images, and networks.

According to the source code in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift), the daemon exposes the primary runtime services that coordinate between the CLI and the lower-level XPC helpers. It maintains the global state of running containers and manages the lifecycle of the lightweight VMs.

## XPC Helper Architecture

The project implements three specialized XPC helper processes that run in isolated address spaces for security and stability. These helpers communicate with the main daemon via XPC and handle specific operational domains:

- **`container-core-images`**: Manages the local OCI content store for container images. Implementation details are found in [`Sources/Plugins/ContainerImagesService/Server/ImagesService.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/ContainerImagesService/Server/ImagesService.swift).

- **`container-network-vmnet`**: Drives the macOS `vmnet` framework to provide virtual networking interfaces. The helper implementation is located in [`Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift).

- **`container-runtime-linux`**: Executes inside the per-container lightweight VM and implements the OCI runtime specification. This critical component resides in [`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift).

## Low-Level Virtualization Layer

The **Containerization Swift package** provides the foundational library that interfaces directly with macOS system frameworks. This package creates the lightweight VM, configures the root filesystem, forwards sockets between host and guest, and manages the virtual hardware.

The `container` CLI depends on this package as noted in the project's [`README.md`](https://github.com/apple/container/blob/main/README.md). While the package abstracts the complexity of the Virtualization framework, it exposes a Swift API for programmatic VM management.

## Plugin Infrastructure

A generic **plugin system** loads the three XPC helpers dynamically at runtime. The `PluginLoader` class in [`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift) discovers available plugins, manages their lifecycle, and exposes a common API for inter-process communication.

This architecture allows the system to extend functionality without modifying the core daemon, adhering to the principle of least privilege by isolating networking and runtime operations in separate processes.

## Build and Persistence Subsystems

The **build subsystem** implements `container build` functionality, parsing `Containerfile` directives and executing build steps in isolated environments. Beyond the main [`Builder.swift`](https://github.com/apple/container/blob/main/Builder.swift) file, the persistence layer in [`Sources/ContainerPersistence/ConfigurationLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ConfigurationLoader.swift) handles encoding and decoding of container configurations, VM snapshots, and the local content store metadata.

## Networking Stack and Diagnostics

The networking implementation includes several specialized components:

- **[`Sources/DNSServer/DNSServer.swift`](https://github.com/apple/container/blob/main/Sources/DNSServer/DNSServer.swift)**: A minimal DNS server that resolves names within the container network namespace.

- **[`Sources/SocketForwarder/TCPForwarder.swift`](https://github.com/apple/container/blob/main/Sources/SocketForwarder/TCPForwarder.swift)**: Forwards TCP and UDP sockets between the macOS host and the Linux VM.

- **[`Sources/ContainerLog/OSLogHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerLog/OSLogHandler.swift)**: Unified logging via `os_log` for diagnostic visibility.

- **[`Sources/TerminalProgress/ProgressBar.swift`](https://github.com/apple/container/blob/main/Sources/TerminalProgress/ProgressBar.swift)**: Provides interactive progress indicators for long-running operations like image pulls and builds.

## Machine API Server

The **`MachineAPIServer`** exposes a gRPC-based API for container-specific operations such as `container exec`. Located in [`Sources/Plugins/MachineAPIServer/MachineAPIServer.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/MachineAPIServer/MachineAPIServer.swift), this service runs as a plugin and provides remote procedure call capabilities for executing commands inside running containers.

## Component Interaction Example

The architecture follows a layered communication pattern. The CLI talks to the daemon via XPC, which then delegates to specific helpers:

```bash

# Start the system daemon

container system start

# Pull and run a container (demonstrates full stack)

container pull docker.io/library/nginx:latest
container run --name my-nginx --publish 8080:80 nginx:latest

```

Programmatically, loading a runtime plugin involves the `PluginLoader` class:

```swift
import ContainerPlugin

let loader = PluginLoader()
let runtimePlugin = try loader.load(name: "container-runtime-linux")
runtimePlugin.start()

```

Creating a VM directly using the Containerization package:

```swift
import Containerization

let vm = try VirtualMachine(
    configuration: .default,
    bundles: [.init(rootPath: "/path/to/rootfs")]
)

try vm.start()

```

## Summary

- **The apple/container project** consists of a CLI (`container`), a system daemon (`container-apiserver`), and three XPC helpers (`container-core-images`, `container-network-vmnet`, `container-runtime-linux`).
- **Key source files** include [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) for builds, [`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift) for plugin management, and [`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift) for OCI runtime implementation.
- **The Containerization Swift package** provides low-level VM management using the macOS Virtualization framework.
- **Networking** relies on `vmnet` framework integration via [`NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/NetworkVmnetHelper.swift) and includes a custom DNS server and socket forwarders.
- **The plugin architecture** enables secure isolation of privileged operations across separate XPC processes.

## Frequently Asked Questions

### What is the purpose of the XPC helpers in apple/container?

The XPC helpers provide process isolation for privileged operations. The `container-core-images` helper manages the OCI content store, `container-network-vmnet` handles virtual networking via the `vmnet` framework, and `container-runtime-linux` executes the OCI runtime spec inside the container's Linux VM. This separation prevents a crash in one component from affecting the entire system.

### How does the container build process work?

The build subsystem, implemented primarily in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift), parses `Containerfile` syntax and orchestrates a build pipeline. It uses protocol buffers (defined in [`Builder.pb.swift`](https://github.com/apple/container/blob/main/Builder.pb.swift)) to communicate build steps, produces OCI-compliant images, and stores them in the local content store managed by the `container-core-images` helper.

### What macOS frameworks does the Containerization package use?

The Containerization Swift package interfaces directly with the **macOS Virtualization framework** to create and manage lightweight Linux VMs, and the **`vmnet` framework** for virtual networking. These frameworks enable Apple silicon Macs to run Linux containers with near-native performance while maintaining proper isolation boundaries.

### How does networking function between the host and containers?

Networking operates through the `container-network-vmnet` helper, which creates virtual interfaces using the `vmnet` framework. The system includes a minimal DNS server ([`Sources/DNSServer/DNSServer.swift`](https://github.com/apple/container/blob/main/Sources/DNSServer/DNSServer.swift)) for name resolution and socket forwarders ([`Sources/SocketForwarder/TCPForwarder.swift`](https://github.com/apple/container/blob/main/Sources/SocketForwarder/TCPForwarder.swift)) to bridge TCP/UDP traffic between the macOS host and the Linux VM running the container.