containerization

Containerization is a Swift package from Apple that lets applications run Linux containers on macOS. It is built on Apple's Virtualization.framework on Apple silicon and exposes a set of APIs for the full container lifecycle. Core capabilities include managing OCI images and interacting with remote registries, creating and populating ext4 file systems, interacting with the Netlink socket family, building an optimized Linux kernel for fast boot times, spawning lightweight virtual machines and managing the runtime environment, spawning and interacting with containerized processes, and using Rosetta 2 to run linux/amd64 containers on Apple silicon. Design-wise, each Linux container runs inside its own lightweight virtual machine. Clients can assign dedicated IP addresses per container, removing the need for individual port forwarding. Containers achieve sub-second start times thanks to an optimized Linux kernel configuration and a minimal root filesystem with a lightweight init system. The vminitd subproject is a small init system spawned as the initial process inside the VM; it exposes a gRPC API over vsock so the runtime environment can be configured and containerized processes launched, and it forwards I/O, signals, and events back to the calling process. The project abstracts the VMM behind VirtualMachineManager / VirtualMachineInstance protocols and ships two backends. The macOS backend uses Virtualization.framework directly (VZVirtualMachineManager) with no extra binaries required. The Linux backend uses cloud-hypervisor plus KVM (CHVirtualMachineManager), running one cloud-hypervisor subprocess per VM controlled over its REST-on-UDS API, with virtio-blk for block storage, virtio-fs (one virtiofsd per share) for shared directories, TAP for networking, and cloud-hypervisor's hybrid vsock to reach the same vminitd contract as the macOS path. The Linux backend requires cloud-hypervisor and virtiofsd on the host, KVM access, and pre-staged TAP/bridge/NAT plumbing for networking. Requirements to build the package are a Mac with Apple silicon, macOS 26, and Xcode 26; older macOS versions are not supported. The Linux guest init (vminitd/vmexec) is compiled as a static binary inside a Linux container rather than cross-compiled on the Mac, so no Swift toolchain or Static Linux SDK is needed on the host — the apple/container CLI is used instead. The cctl executable serves as a playground for exploring the API, with commands for manipulating OCI images, logging into registries, creating root filesystem blocks, and running simple Linux containers. A Linux kernel is required to spawn lightweight VMs on macOS. The repository includes an optimized kernel configuration in the kernel/ directory with a containerized build environment for compiling it. The configuration is minimal to support fast start times and a lightweight environment, and Containerization provides first-class APIs to use different kernel configurations and versions on a per-container basis. User-provided kernels are supported, with functionality tested starting from kernel version 6.14.9. Pre-built kernels must have VIRTIO drivers compiled into the kernel (not merely as modules); the Kata Containers project provides a suitable kernel. Build and test workflow: install the recommended Xcode, set the active developer directory, install the apple/container CLI, then run `make all` to build and `make test integration` to run tests. A kernel is required for integration tests; `make fetch-default-kernel` fetches a default one. Protobuf interfaces can be regenerated with `make protos`, a pre-commit hook can be installed with `make pre-commit`, and API documentation can be generated locally with `make docs` and `make serve-docs`. The project is at version 0.1.0, the first official release. Source stability is only guaranteed within minor versions (for example, between 0.1.1 and 0.1.2); consumers who want to avoid potentially source-breaking updates can pin dependencies with .upToNextMinorVersion(from: "0.1.0"). Contributions are welcomed via the CONTRIBUTING.md file.