Build something like this?

Apple container: architecture map

A map of Apple's Swift container project, drawn from the source code across 18 layered boards (351 components, 410 connections). It includes three findings: how k8s create gets from the command to logging, where the services layer connects to the rest of the system, and what fails if the shared test fixture breaks. Two focused views show the CLI entry point and how far a failure in the XPC extensions would spread.

1 layer1 insightby Supportv2Published Oct 30, 2026

The map

The map · Spine

Architecture

What's on this map
  • AI coding agent · actor
  • Build & release tooling · infrastructure component
  • BuildKit builder (container-builder-shim) · external integration
  • Container agent skill · agent skill
  • Containerization framework · library package
  • Developer on a Mac · actor
  • External services · external integrations
  • GitHub · github
  • Kata Containers kernel release · external integration
  • macOS Keychain · data store
  • Kubernetes cluster (kind node + kubeadm) · external integration
  • launchd · infrastructure component
  • macOS host platform · infrastructure group
  • OCI image registries · external integration
  • Workloads it provisions · domain group
  • Container system (CLI + services) · desktop app
  • Virtualization.framework · infrastructure component
  • vmnet · infrastructure component

The map · Layers

Layers1

What's on each layer

container system (CLI + services)

Inside `Sources/`: the `container` CLI, the `container-apiserver` launchd agent, the plugin helpers (images, vmnet networking, Linux runtime, machines, Kubernetes) and the shared Swift libraries they are built from, connected over XPC. Container-grade with 8 drill-downs.

  • Command line · domain group
  • container-apiserver · service
  • ContainerBuild · module
  • container CLI executable · desktop app
  • ContainerCommands · module
  • ContainerK8s · module
  • ContainerLog · module
  • ContainerOS · module
  • ContainerPersistence · module
  • ContainerPlugin · module
  • ContainerResource · module
  • ContainerTestSupport · module
  • ContainerVersion · module
  • ContainerXPC · module
  • container-core-images · plugin
  • DNSServer · module
  • k8s plugin executable · plugin
  • Kubernetes plugin · domain group
  • launchd services · domain group
  • machine-apiserver · plugin
  • container-network-vmnet · plugin
  • container-runtime-linux · plugin
  • Service APIs (XPC clients + servers) · module
  • Shared foundation · platform foundation
  • SocketForwarder · module
  • TerminalProgress · module

ContainerBuild

ContainerBuild is the macOS-host side of the OCI/Docker image build pipeline: a gRPC client (Builder) that dials the Linux builder-shim VM, streams build-context files, resolves and proxies base images, and relays build output, layered on generated protobuf/gRPC wire types for the Builder service. Grain: terminal — the component-layer group plan reads `fits` (13 nodes vs band 5-20) with no drill-down candidates, so this board stops at component grain.

  • Build API Extensions · module
  • Builder · facade component
  • Builder gRPC Client · class interface
  • Builder Protocol Messages · schema model
  • Build File · module
  • Build FS Sync · handler component
  • Build Image Resolver · handler component
  • Build Pipeline · controller component
  • Build Protocol · domain group
  • Build Remote Content Proxy · adapter component
  • Build Stdio · handler component
  • Globber · engine component
  • Pipeline Handlers · domain group
  • ContainerPersistence · boundary port
  • Service APIs (XPC clients + servers) · boundary port
  • TerminalProgress · boundary port
  • Support Utilities · domain group
  • Terminal Command · module
  • URL Extensions · module

ContainerCommands

The Swift ArgumentParser command tree behind the `container` CLI: the root Application command, per-resource groups (Builder, Image, Network, Registry, Volume), and shared plumbing (logging protocol, output rendering, utilities). Container-grade board: the group plan read over-band (48 vs band 5-20) on directory-fallback evidence, so files fold into one node per resource family; Container, Machine, System and Image stay opaque drill-downs.

  • Application · facade component
  • AsyncLoggableCommand · class interface
  • Builder Commands · controller component
  • CLI Bootstrap · domain group
  • CLI Utilities · module
  • Container · controller component
  • Default Command · handler component
  • Help Command · handler component
  • Image Commands · controller component
  • Machine · controller component
  • Network Commands · controller component
  • Output Rendering · module
  • ContainerBuild · boundary port
  • ContainerLog · boundary port
  • ContainerPersistence · boundary port
  • ContainerPlugin · boundary port
  • ContainerResource · boundary port
  • ContainerVersion · boundary port
  • ContainerXPC · boundary port
  • DNSServer · boundary port
  • Service APIs (XPC clients + servers) · boundary port
  • TerminalProgress · boundary port
  • Registry Commands · controller component
  • Resource Commands · domain group
  • System · controller component
  • Volume Commands · controller component

Container

The `container` resource command group of the `container` CLI: create/run/exec/list/logs/stop/kill/delete/export/copy/prune/stats/clean subcommands plus two shared display/validation helpers. Grain: terminal — over-band is the directory-fallback leaf-file count of 17 already-atomic, individually significant CLI command files with no lower layer to drill into; grouped into four functional domain clusters for readability rather than proposing further depth.

  • Container Clean · controller component
  • Container Copy · controller component
  • Container Create · controller component
  • Container Delete · controller component
  • Container Exec · controller component
  • Container Export · controller component
  • Container Inspect · controller component
  • Container Kill · controller component
  • Container List · controller component
  • Container Logs · controller component
  • Container Prune · controller component
  • Container Run · controller component
  • Container Start · controller component
  • Container Stats · controller component
  • Container Stop · controller component
  • Data & Maintenance · domain group
  • Inspection & Monitoring · domain group
  • Lifecycle & Execution · domain group
  • ManagedContainer+ListDisplayable · module
  • ProcessUtils · module
  • Shared Utilities · domain group

Image Commands

The `container image` command group (pull, push, save, load, list, inspect, tag, delete, prune) and `container build`: thin ArgumentParser commands that delegate to the image service client and the BuildKit builder. Terminal: one node per file (12) in two containers, within the 5–15 band.

  • container build · controller component
  • container image · controller component
  • container image delete · controller component
  • container image inspect · controller component
  • container image list · controller component
  • container image load · controller component
  • container image prune · controller component
  • container image pull · controller component
  • container image push · controller component
  • ImageResource list rows · module
  • container image save · controller component
  • container image tag · controller component
  • Local image store · domain group
  • Registry & archive transfer · domain group

Machine

The `machine` CLI command family: create, inspect, list, run, configure and tear down the lightweight VM ("container machine") that hosts Linux containers on macOS, plus the shared boot/capability helpers the subcommands call into. Grain: terminal — the group plan predicts 12 nodes against a 5-15 band with a fits verdict and no drill-down clusters, so this board stops at component grain.

  • Machine Capabilities · service component
  • Machine Command · controller component
  • Machine Create · handler component
  • Machine Delete · handler component
  • Machine Helpers · service component
  • Info & Config Commands · domain group
  • Machine Inspect · handler component
  • Lifecycle Commands · domain group
  • Machine List · handler component
  • Machine Logs · handler component
  • Machine Run · handler component
  • Machine Set · handler component
  • Machine Set Default · handler component
  • Shared Helpers · domain group
  • Machine Stop · handler component

System

The `container system` CLI command family: service lifecycle (start/stop/status/logs/df/version) plus the DNS, kernel, and property subcommand groups. Terminal board: the group plan's over-band verdict rests on directory-fallback evidence (one flat cluster covering the whole scope); this unit carries no further child boards and its 15 files are already atomic, single-purpose ArgumentParser command structs, so component grain is correct here.

  • DNS Commands · domain group
  • DNSCreate · controller component
  • DNSDelete · controller component
  • DNSList · controller component
  • KernelSet · controller component
  • PropertyList · controller component
  • SystemCommand · controller component
  • SystemDF · controller component
  • SystemDNS · controller component
  • SystemKernel · controller component
  • SystemLogs · controller component
  • SystemProperty · controller component
  • SystemStart · controller component
  • SystemStatus · controller component
  • SystemStop · controller component
  • SystemVersion · controller component

ContainerK8s

The `ContainerK8s` library behind the `container k8s` plugin: CLI commands (create/delete/list/load-image/start/write-config), the K8sHelper cluster-lifecycle engine (bootstrap/image/kubeconfig/networking/readiness), the KubeConfig schema, and the NodeProvisioner protocol with its LinuxNodeProvisioner implementation. Terminal grain: layer-2 plan predicts 17 nodes vs band 5-20, no drill-downs proposed.

  • K8s CLI Commands · domain group
  • Cluster Lifecycle Engine · domain group
  • K8s Create · handler component
  • K8s Delete · handler component
  • K8s Helper (Core) · engine component
  • K8s Helper + Bootstrap · engine component
  • K8s Helper + Image · engine component
  • K8s Helper + Kubeconfig · engine component
  • K8s Helper + Networking · engine component
  • K8s Helper + Readiness · engine component
  • K8s List · handler component
  • K8s Load Image · handler component
  • K8s Start · handler component
  • K8s Write Config · handler component
  • KubeConfig Schema · schema model
  • Linux Node Provisioner · adapter component
  • Node Provisioner (Protocol) · class interface
  • Node Provisioning · domain group
  • ContainerLog · boundary port
  • ContainerPersistence · boundary port
  • ContainerPlugin · boundary port
  • ContainerResource · boundary port
  • Service APIs (XPC clients + servers) · boundary port
  • TerminalProgress · boundary port
  • Table Output · module

ContainerPersistence

ContainerPersistence: TOML-layered system/machine configuration loading and decoding, a filesystem-backed EntityStore, and shared memory-size/path parsing utilities used across the container CLI and daemon. Grain: terminal — component grain, no drill-down (group plan budgetVerdict: fits, 12 significant files, directory-fallback evidence).

  • Config Coding Strategy · adapter component
  • Config Decoding Engine · domain group
  • Config Data Models · domain group
  • Config Snapshot Decoder · engine component
  • Config Snapshot Decoder Containers · engine component
  • Configuration Loader · service component
  • Container System Config · schema model
  • Entity Store · repository component
  • File Path Symlinks · module
  • Machine Config · schema model
  • Measurement Parse · module
  • Memory Size · module
  • Parsers · module
  • Path Utils · module
  • Persistence Utilities · domain group
  • ContainerVersion · boundary port

ContainerResource

The ContainerResource Swift module — shared, Codable resource-model types (Container, Image, Network, Registry, Volume) and common protocols used across the container system's client and daemon components for XPC transport and persistence. Board grain: terminal — one node per significant file, all schema/interface-role types, no further drill-downs beyond the already-separated Container child board (15 own files + 1 opaque child unit = 16 nodes, fits band 5-20).

  • Application Error · class interface
  • Attachment · schema model
  • Attachment Configuration · schema model
  • Common Foundation · domain group
  • Container · schema model
  • File Manager Allocated Size · module
  • Image Description · schema model
  • Image, Registry & Volume Resources · domain group
  • Image Resource · schema model
  • Managed Resource · class interface
  • Network Configuration · schema model
  • Network Mode · schema model
  • Network Resource · schema model
  • Network Resources · domain group
  • Network Status · schema model
  • Registry Resource · schema model
  • Resource Labels · schema model
  • Volume Configuration · schema model
  • Volume Resource · schema model

Container

The Container resource model: value types describing a container's configuration, runtime status, and the options used to create, list, and stop it. Terminal grain — 14 files, one node per significant type, directory-fallback grouping (no coupling graph over such a small, cohesive value-type set), plan budget fits (14 in band 5-15) with no drill-downs proposed.

  • Bundle · class interface
  • Configuration & Bundle · domain group
  • ContainerConfiguration · schema model
  • ContainerCreateOptions · schema model
  • ContainerListFilters · schema model
  • ContainerSnapshot · schema model
  • ContainerStats · schema model
  • ContainerStatus · schema model
  • ContainerStopOptions · schema model
  • Filesystem · schema model
  • ManagedContainer · aggregate
  • ProcessConfiguration · schema model
  • PublishPort · schema model
  • PublishSocket · schema model
  • RuntimeStatus · schema model
  • Status & Lifecycle · domain group

ContainerTestSupport

ContainerTestSupport — a Swift test-support library providing the ContainerFixture per-test harness (CLI execution, resource lifecycle tracking, cleanup) plus lifecycle helper extensions and test doubles used by the CLI integration test suite. Terminal board — group plan reads budgetVerdict "fits" (14 files, band 5-20), no drill-downs.

  • Build Fixture · engine component
  • Command Result · class interface
  • Container Fixture · facade component
  • Container Helpers · adapter component
  • Core Fixture & Command Execution · domain group
  • Image Helpers · adapter component
  • Kernel Fixture · engine component
  • Loopback File Server · handler component
  • Machine Helpers · adapter component
  • Network Helpers · adapter component
  • ContainerLog · boundary port
  • ContainerPersistence · boundary port
  • ContainerPlugin · boundary port
  • ContainerResource · boundary port
  • Resource Lifecycle Helpers · domain group
  • SSH Test Helpers · adapter component
  • System Helpers · adapter component
  • Temporary Storage · module
  • Test Doubles & Utilities · domain group
  • Volume Helpers · adapter component
  • Warmup Image · class interface

DNSServer

Inside `Sources/DNSServer`: a minimal embedded DNS server that answers A/AAAA queries for containers over UDP or a Unix domain socket, using a chain of composable resolver handlers backed by a static host table, plus the RFC 1035 wire-format model it serializes against. Terminal — the group plan's `directory-fallback` verdict fits within band at 16 files with no proposed drill-downs.

  • Composite Resolver · handler component
  • DNS Bind Error · schema model
  • DNS Protocol Enums · schema model
  • DNS Handler Contract · class interface
  • DNS Message · schema model
  • DNS Name · schema model
  • DNS Query Resolvers · domain group
  • DNS Question · schema model
  • DNS Server · engine component
  • DNS Server Core · domain group
  • DNS Wire Protocol · domain group
  • Host Table Resolver · handler component
  • NXDOMAIN Resolver · handler component
  • Resource Record · schema model
  • Standard Query Validator · handler component
  • Wire Binary Utility · module

Service APIs (XPC clients + servers)

The XPC-based helper services under `Sources/Services/` (excluding ContainerAPIService, which drills down separately): image/content storage, host networking (default and vmnet-backed), the machine (VM) lifecycle API, and the per-runtime client plus its Linux implementation and socket-forwarding engine. Terminal component grain: the plan's own scope (41 files) groups into 10 client/server component pairs with no cluster large or dense enough to warrant a further drill-down.

  • Container API Service · module
  • Image & Content Service · domain group
  • Images Service · service component
  • Images Service Client · adapter component
  • Machine API · domain group
  • Machine Client · adapter component
  • Machine Service · service component
  • Network Client · adapter component
  • Networking · domain group
  • Network Service · service component
  • Vmnet Network Service · service component
  • ContainerOS · boundary port
  • ContainerPersistence · boundary port
  • ContainerPlugin · boundary port
  • ContainerResource · boundary port
  • ContainerVersion · boundary port
  • ContainerXPC · boundary port
  • DNSServer · boundary port
  • TerminalProgress · boundary port
  • Runtime Client · adapter component
  • Runtime Linux Service · service component
  • Runtime & Sandbox · domain group

Container API Service

The main ContainerAPIService/ContainerAPIClient XPC service that the `container` CLI talks to for container, disk-usage, health-check, kernel, network, plugin and volume operations, split into its Client and Server libraries. Terminal board: this unit claims 0 files of its own — the tree plan already carved its full 45-file scope into exactly the Client and Server child units carried here as opaque nodes, so there is no further grouping or drill-down for this agent to decide.

  • Client · adapter component
  • Images Service Client · boundary port
  • Network Client · boundary port
  • Runtime Client · boundary port
  • Server · service component

Client

The ContainerAPIService Client library: the ContainerClient-centered XPC client surface the container CLI links against, its per-domain resource clients, XPC transport, CLI spec parsing, platform/network helpers, and shared utilities. Terminal board: all 32 files are significant, individually-typed components; grouping-plan evidence was directory-fallback (no coupling signal), so containment here is grouped by domain from a direct reading of the code.

  • Archiver · engine component
  • Array+Dedupe · module
  • ClientDiskUsage · adapter component
  • ClientHealthCheck · adapter component
  • ClientImage · adapter component
  • ClientKernel · adapter component
  • ClientProcess · adapter component
  • ClientVolume · adapter component
  • CLI Spec Parsing · domain group
  • Common Extensions · domain group
  • Constants · module
  • ContainerClient · facade component
  • ContainerizationProgressAdapter · adapter component
  • Container & Volume Clients · domain group
  • DefaultPlatform · module
  • DiskUsage · module
  • FileDownloader · engine component
  • Flags · module
  • HostDNSResolver · adapter component
  • ImageLoadResult · module
  • NetworkClient · adapter component
  • PacketFilter · engine component
  • Parser · engine component
  • Platform & Networking · domain group
  • ProcessIO · engine component
  • Process & Kernel Clients · domain group
  • ProgressUpdateClient · handler component
  • ProgressUpdateService · handler component
  • RequestScheme · module
  • SignalThreshold · module
  • String+Extensions · module
  • SystemHealth · module
  • System Utilities · domain group
  • Utility · module
  • XPC+ · module
  • XPC Transport · domain group

Server

XPC request handlers (Harness) and business-logic actors (Service) for each API resource the apiserver's Server target exposes — containers, disk usage, kernel images, networks, plugins, and volumes — plus the standalone health-check endpoint. Grain: terminal — the grouping plan fits within this board's node band with no proposed drill-downs, so each resource's Harness/Service pair is drawn as a small domain_group of two components rather than boxed into further sub-boards.

  • Containers · domain group
  • ContainersHarness · handler component
  • ContainersService · service component
  • Disk Usage · domain group
  • DiskUsageHarness · handler component
  • DiskUsageService · service component
  • HealthCheckHarness · handler component
  • Kernel · domain group
  • KernelHarness · handler component
  • KernelService · service component
  • Networks · domain group
  • NetworksHarness · handler component
  • NetworksService · service component
  • Plugin · domain group
  • PluginsHarness · handler component
  • PluginsService · service component
  • Client · boundary port
  • Volumes · domain group
  • VolumesHarness · handler component
  • VolumesService · service component

What to notice

Inbound · Signals

Insights1 analysis

1Insights
0Critical
observation1
Read all 1

K8s Create only tears down the cluster if it fails before the kubeconfig step

observation · medium · verified

container k8s create handles failures differently depending on when they happen. An error while provisioning the node, running kubeadm init or waiting for readiness tears the node container down and removes any partial kubeconfig. If only the kubeconfig write fails, it logs a warning, leaves the cluster running and points to write-config. It also loads system config from local defaults, not from the daemon's roots as the main CLI does.

Impact: An operator who hits a kubeconfig failure gets a running cluster with no obvious error, and only a log line points them to the fix; anyone scripting create has to check for that case separately from every other failure, which tears everything down.

Recommendation (small effort): Have create surface the kubeconfig failure at error level (not just a warning) and print the write-config recovery command to standard error, so the difference between "nothing happened" and "cluster is up but unconfigured" is visible without reading logs.

  1. K8s Create
  2. ContainerLog
  3. ContainerLog
  4. K8s Helper + Bootstrap

In the code

Endpoints 86 · Clients 3

Inbound · From code

Endpoints

86endpoints

Public
3
Deprecated
0
Rate-limited
0
By method
  • GRPC86

Endpoints

+82 more

Inbound · From code

Clients

3clients

HTTP
2
gRPC
1
Calls
4
Calls by target
  • buildkit3
  • github.com1
  • docker.io0

Clients