apple/containerization is a Swift package and CLI for running Linux containers inside lightweight virtual machines. On macOS it drives Virtualization.framework; on Linux it drives Cloud Hypervisor + KVM. The public surface is the Containerization library (consumed programmatically via SwiftPM) plus the cctl command-line tool (image pull/push/save/load, login, rootfs creation, run), with vminitd as the guest-side init agent. The code defines the actual boundaries: OCI registry clients, ext4 image building, VM boot, and in-guest process supervision. The examples/ directory includes a minimal consumer (ctr-example) and a full application (sandboxy) that runs AI coding agents in sandboxed Linux VMs, but the repo itself is a container-runtime framework, not an AI product. Architecture is a multi-module SwiftPM package. Containerization defines the core protocols (Container, VirtualMachineManager, VirtualMachineInstance, Network, Mount, Kernel) with macOS VZ and Linux Cloud Hypervisor implementations; ContainerizationOCI implements the OCI image spec and a full registry client (token auth, realm validation, referrers API, push/pull/catalog) over content-addressed, digest-verified storage; ContainerizationOS provides syscall wrappers, TOCTOU-safe fd-relative filesystem operations, sockets, PTYs, and process reaping; ContainerizationEXT4 is a hand-written ext4 formatter/reader that creates root filesystems and unpacks image layers; ContainerizationNetlink handles Linux interface/route configuration; ContainerizationArchive wraps libarchive with traversal protection; CloudHypervisor is a typed REST client over Unix-domain sockets. Inside the guest, vminitd exposes a gRPC API over vsock (generated from SandboxContext.proto) and performs mounts, cgroups v2 management, process supervision, and stdio relay, launching containers via either runc or the native vmexec helper. Key data flows: images are pulled from Docker Hub/GHCR/other OCI registries through RegistryClient, validated by SHA-256 digest, stored in an ImageStore, unpacked into ext4 root filesystems, then booted as VMs with virtiofs/virtio-blk mounts, bridged TAP networking (iptables NAT on Linux, vmnet on macOS), and vsock-connected stdio. Runtime dependencies include cloud-hypervisor, virtiofsd, and runc binaries, libarchive/zstd C libraries, and a custom Linux kernel (6.18.5) built from in-repo configs. Testing is extensive: per-module unit tests using Swift Testing plus a large integration suite covering process lifecycle, TTY, seccomp, capabilities, cgroup limits, volumes, pods, and network statistics. Engineering quality is high and security-conscious: digest parsing rejects traversal digests, filesystem primitives default to not following symlinks, seccomp profiles are derived from containerd with capability gating, and registry token requests validate realms to prevent SSRF. Maintenance is active with recent commits and CI for both platforms. The main risks are breadth-driven: two VMM backends and two runtime backends (runc vs vmexec) must stay in sync, the hand-maintained ext4 and seccomp implementations must track kernel/upstream changes, and external binaries are pinned rather than auto-updated.
This repository is Apple's `container` tool: a Docker-compatible CLI and background service that runs Linux containers as lightweight virtual machines on Apple silicon macOS. The production system is a multi-process, XPC-based client-server architecture: a `container` CLI (ArgumentParser-based) talks to a `container-apiserver` daemon over XPC, which manages container lifecycle (create/run/exec/kill/stats), OCI image pull/push/save/load, volumes (ext4 images), networks (vmnet plugin), and machine VMs (Virtualization.framework). A plugin system registered with launchd (`container-runtime-linux`, `container-network-vmnet`, `container-core-images`, `machine-apiserver`, plus an experimental kind-like `k8s` plugin for local Kubernetes clusters) handles runtime and networking duties. Image builds are delegated to a BuildKit shim running in a Linux VM over a gRPC/protobuf protocol, with context transfer handled by a custom fssync walker.