How apple/containerization works
Project Type and Purpose
• Containerization is a Swift-based library and toolset for running Linux containers on Apple Silicon macOS.
• It consists of:
• A core Swift package (“Containerization”) providing APIs for OCI images, ext4, netlink, VM management, etc.
• A CLI playground called cctl that exercises the core APIs.
• A minimal init system subproject (vminitd) that runs inside the VM and exposes a gRPC/vsock API.
• An optimized Linux kernel build environment under /kernel.
Top-Level Components (
A. Host‐Side (macOS)
1. cctl CLI (Sources/cctl) – command‐line client.
2. Containerization Library (Sources/Containerization, …/OCI, …/EXT4, …/Netlink, …/OS, …/Extras, …/Archive, …/IO) – modules that:
• Manage OCI images & registries (ContainerizationOCI + remote registry).
• Assemble ext4 rootfs (ContainerizationEXT4 + Archive).
• Configure networking (ContainerizationNetlink + NAT interfaces).
• Interact with macOS kernel / Virtualization.framework (Containerization/LinuxContainer, VZVirtualMachineManager, etc.).
3. Virtualization.framework (Apple API) – abstracts VZVirtualMachine, virtual network, vsock device.
4. gRPC‐Swift + Swift-Protobuf – used by vminitd protocol stubs.
5. Build & Test Infrastructure (Makefile, GitHub Actions workflows).
B. VM-Side (Lightweight VM)
1. Linux Kernel image (vmlinux.container) – loaded by Virtualization.framework.
2. vminitd (Sources in /vminitd) – small init daemon running as PID 1, embedding:
• vsock gRPC server (Server+GRPC.swift).
• ProcessSupervisor, ManagedContainer, ManagedProcess.
• Host ↔ guest I/O multiplexing, signal forwarding, terminal support.
3. Root filesystem – ext4 image produced by ContainerizationEXT4.
4. Containerized processes – launched by vminitd on host’s request.
C. External Services
1. OCI Registry – remote image registry accessed via ContainerizationOCI/Client.
2. Pre-built Kernel Sources – from Kata Containers or custom.
Component Interactions & Data Flows
• cctl or any host application → calls Containerization Library APIs →
• Uses OCI client to pull/push images ←→ OCI registry (HTTPS).
• Uses EXT4 writer to build rootfs image (local file).
• Uses Virtualization.framework to configure & launch a VZVirtualMachine with:
– Kernel image
– Rootfs ext4 image
– vsock device enabled
– VM networking (vmnet)
• Once VM boots: vminitd starts inside VM → listens on vsock for gRPC calls →
• Host : gRPC client stub (Containerization/SandboxContext) ↔ vsock → vminitd
• Host requests “create container,” “start process,” “attach IO,” “cleanup.”
• vminitd supervises container namespaces, forks processes, attaches stdio.
• Networking: Containerization NAT interfaces on macOS ↔ virtual NIC inside VM.
Architectural Patterns & Principles
• Modular Swift Packages: clear separation by functionality (OCI, EXT4, Netlink, OS abstraction).
• Client-Server via vsock/gRPC: decouples host tooling from in-VM init.
• Single Responsibility: vminitd only manages guest processes; host library handles image, VM orchestration.
• Extensibility: each Swift module exposes protocols (e.g., ContentStoreProtocol) to allow alternative implementations.
• Reuse of existing APIs: leverages Virtualization.framework, gRPC-Swift, swift-protobuf.
Diagramming Conventions
• Clear, descriptive labels on every component.
• Host code (blue),
• Virtualization/framework (gray),
• VM internals (green),
• External services (orange).