Deep Dive into Apple Container

Introduction

Container is an open source command line tool provided by Apple. It is built for running Linux container on Mac, especially optimized for Apple Silicon. It is wrote in Swift, and built with Containerization Framework . The Apple Containerization and Container CLI are released on WWDC 2025.

Further reading:

• Apple Releases Containerization Framework: Ushering in a New Era of macOS Containerization
• Apple Container Unboxing & Practice

Apple Container is a client-server architecture system that enables containerized workloads on macOS. This post explores its architecture, startup sequence, core plugins, and extensibility considerations.

Architecture Overview

Apple Container leverages several key technologies and frameworks:

• Virtualization framework
• vmnet framework
• XPC
• Launchd
• Keychain
• Unified logging system

The system uses a client-server model where the CLI communicates with the container-apiserver and its helpers.

Startup Sequence

After installing the container, the first command to execute is:

container system start

Without this command, running other commands results in errors like XPC connection error: Connection invalid. This is because the CLI relies on a client to communicate with container-apiserver, which is a launch agent started by container system start. The apiserver provides APIs to manage container and network resources.

XPC provides a lightweight mechanism for interprocess communication (IPC) between clients and services via peer-to-peer connections. XPC services are managed by the launchd system, which starts and stops services as needed.

When container-apiserver starts, it launches core plugins located in /usr/local/libexec/container/plugins. These plugins are XPC services. After launching, the three core services are ready for use.

ls -l /usr/local/libexec/container/plugins
total 0
drwxr-xr-x  4 root  wheel  128 Jun 10 04:04 container-core-images
drwxr-xr-x  4 root  wheel  128 Jun 10 04:04 container-network-vmnet
drwxr-xr-x  4 root  wheel  128 Jun 10 04:04 container-runtime-linux

Core Plugins

The core plugins and their responsibilities:

• container-core-images (com.apple.container.core.container-core-images): APIs for images and local content store management. Supports pulling, pushing, and managing container images.
• container-network-vmnet (com.apple.container.network.container-network-vmnet): APIs for network management, enabling creation and management of container networks using the vmnet framework.
• container-runtime-linux (com.apple.container.runtime.container-runtime-linux): APIs for container runtime management, allowing creation and management of Linux containers using the Virtualization framework.

The core plugin interacts through the APIs provided by Containerization Framework, supporting the creation, management, and network configuration of containerized workloads. I’ll write a separate article to explain how the Containerization Framework works when I have time.

Extensibility

Besides bundled plugins, container-apiserver loads user plugins from:

/Users/addo/Library/Application Support/com.apple.container/user-plugins

Currently, there are no user plugins, but this directory allows developers to extend container functionality by creating their own plugins.

Summary

Apple Container combines macOS frameworks and a modular plugin system to deliver containerized environments. Understanding its architecture and extensibility points helps developers leverage and extend its capabilities for advanced workflows.