# apple/containerization architecture

> Architecture diagram of the GitHub repository apple/containerization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apple/containerization
- Repository: https://github.com/apple/containerization

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host Application Layer
    subgraph "Host Application Layer"
        direction TB
        cctl["cctl CLI"]:::host
        Containerization["Containerization Library"]:::host
    end

    cctl -->|uses APIs| Containerization

    %% Containerization sub-modules
    subgraph "Containerization Modules"
        direction TB
        OCIClient["OCI Client"]:::host
        OCIContent["OCI Content Store"]:::host
        EXT4Builder["EXT4 Rootfs Builder"]:::host
        Archive["Archive Support"]:::host
        Netlink["Netlink Networking"]:::host
        OSAbstractions["OS Abstractions"]:::host
        Extras["Extras"]:::host
        IOStreams["I/O Streams"]:::host
        VMManager["VM Manager"]:::host
        SandboxContext["SandboxContext (gRPC stubs)"]:::host
        CShim["CShim"]:::host
    end

    Containerization --> OCIClient
    Containerization --> OCIContent
    Containerization --> EXT4Builder
    Containerization --> Archive
    Containerization --> Netlink
    Containerization --> OSAbstractions
    Containerization --> Extras
    Containerization --> IOStreams
    Containerization --> VMManager
    Containerization --> SandboxContext
    Containerization --> CShim

    %% External Services
    OCIRegistry["OCI Registry (HTTPS)"]:::ext
    HostNet["Host Network Stack"]:::ext

    OCIClient -->|pull/push images| OCIRegistry
    Netlink -->|configures NAT| HostNet

    %% Virtualization.framework
    VZFW["Virtualization.framework"]:::virt

    Containerization -->|launch VM, vsock| VZFW

    %% VM Side
    subgraph "Lightweight VM" 
        direction TB
        LinuxKernel["Linux Kernel"]:::vmintern
        Rootfs["Rootfs ext4"]:::vmintern
        vminitd["vminitd (gRPC Server over vsock)"]:::vmintern
        Processes["Containerized Processes"]:::vmintern
    end

    VZFW --> LinuxKernel
    VZFW --> Rootfs
    VZFW --> vminitd
    vminitd --> Processes

    SandboxContext -->|gRPC over vsock| vminitd

    %% Kernel Build
    KernelBuild["Kernel Build Environment"]:::ext
    PrebuiltKernel["Pre-built Kernel Image"]:::ext

    KernelBuild --> PrebuiltKernel
    PrebuiltKernel --> LinuxKernel

    %% Build & CI
    subgraph "Build & Test Infrastructure"
        direction TB
        MakefileNode["Makefile"]:::ci
        GitHubActions[".github/workflows"]:::ci
        ProtoMake["Protobuf.Makefile"]:::ci
    end

    MakefileNode -->|triggers| cctl
    GitHubActions -->|runs| Containerization
    ProtoMake -->|generates stubs| SandboxContext

    %% Click Events
    click cctl "https://github.com/apple/containerization/tree/main/Sources/cctl/"
    click Containerization "https://github.com/apple/containerization/tree/main/Sources/Containerization/"
    click OCIClient "https://github.com/apple/containerization/tree/main/Sources/ContainerizationOCI/Client/"
    click OCIContent "https://github.com/apple/containerization/tree/main/Sources/ContainerizationOCI/Content/"
    click EXT4Builder "https://github.com/apple/containerization/tree/main/Sources/ContainerizationEXT4/"
    click Archive "https://github.com/apple/containerization/tree/main/Sources/ContainerizationArchive/"
    click Netlink "https://github.com/apple/containerization/tree/main/Sources/ContainerizationNetlink/"
    click OSAbstractions "https://github.com/apple/containerization/tree/main/Sources/ContainerizationOS/"
    click Extras "https://github.com/apple/containerization/tree/main/Sources/ContainerizationExtras/"
    click IOStreams "https://github.com/apple/containerization/tree/main/Sources/Containerization/IO/"
    click VMManager "https://github.com/apple/containerization/blob/main/Sources/Containerization/VZVirtualMachine+Helpers.swift"
    click VMManager "https://github.com/apple/containerization/blob/main/Sources/Containerization/VZVirtualMachineManager.swift"
    click VMManager "https://github.com/apple/containerization/blob/main/Sources/Containerization/VirtualMachineManager.swift"
    click SandboxContext "https://github.com/apple/containerization/tree/main/Sources/Containerization/SandboxContext/"
    click CShim "https://github.com/apple/containerization/tree/main/Sources/CShim/"
    click vminitd "https://github.com/apple/containerization/tree/main/vminitd/Sources/vminitd/"
    click LCShim "https://github.com/apple/containerization/tree/main/vminitd/Sources/LCShim/"
    click vmexec "https://github.com/apple/containerization/tree/main/vminitd/Sources/vmexec/"
    click KernelBuild "https://github.com/apple/containerization/tree/main/kernel/"
    click PrebuiltKernel "https://github.com/apple/containerization/tree/main/kernel/image/"
    click MakefileNode "https://github.com/apple/containerization/tree/main/Makefile"
    click GitHubActions "https://github.com/apple/containerization/tree/main/.github/workflows/"
    click ProtoMake "https://github.com/apple/containerization/blob/main/Protobuf.Makefile"

    %% Styles
    classDef host fill:#D0E8FF,stroke:#0000FF
    classDef virt fill:#EEEEEE,stroke:#888888
    classDef vmintern fill:#DDFFDD,stroke:#00AA00
    classDef ext fill:#FFE0B2,stroke:#FF8800
    classDef ci fill:#FFF3B0,stroke:#CC9900
```
