$ show apple/containerization
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.
The LLM identified 8 files worth highlighting for reuse:
Parses /proc/net/snmp and /proc/net/netstat into typed per-namespace traffic counters. The parser tolerates new or reordered kernel columns by validating known fields and ignoring unknown ones, making it robust against kernel version drift. Fully self-contained with no internal module dependencies; directly reusable in any Linux telemetry or network-monitoring tool.
Async-safe mutex with reentrancy protection, designed for use from Swift async/await contexts without blocking the cooperative thread pool. Backed by a comprehensive test suite covering recursion and contention. Standalone and extractable for any Swift server, CLI, or library needing async-friendly locking.
TOCTOU-safe filesystem primitives anchored to directory file descriptors using openat/O_NOFOLLOW (with O_RESOLVE_BENEATH on macOS). The SymlinkPolicy abstraction makes symlink-following explicit rather than implicit, protecting against symlink-escape and race attacks. Directly transferable to package managers, archive extractors, sandboxes, and other security-sensitive tooling.
High-level, message-typed wrapper over netlink sockets for interface, address, and route operations, with a Bindable binary serialization protocol and a mockable session abstraction for tests. Reusable beyond containers for any Linux network configuration tool or daemon that needs to manipulate links/routes programmatically.
ParsedDigest type that strictly validates sha256:<hex> references and constructs traversal-safe path components for blob storage. Guards against digest poisoning and path traversal in content-addressed stores; the validation-and-safe-path pattern applies to any OCI-compatible or hash-addressed artifact system.
Asynchronous deadline helper that races an operation against a timeout and cancels it cleanly, with tests verifying cancellation behavior. Tiny, dependency-free, and reusable in any Swift API that needs bounded waits without leaking tasks.
Generic archive reader over the vendored libarchive C shim that rejects path-traversal entries and symlink escapes during extraction, with explicit last-entry-wins semantics. Solves a recurring security problem in image, artifact, and dependency pipelines; extractable together with the CArchive bridge for use in other Swift tools.
Pure-Swift read-only ext4 implementation covering superblock parsing, block groups, extent trees, inline extended attributes, and symlink resolution, with tests validating geometry against real filesystem images. Non-obvious filesystem craftsmanship; usable as a standalone ext4 inspection library for forensics, build systems, or image validation without needing mount privileges.