apple/containerization

 Containerization

The Containerization package allows applications to use Linux containers. Containerization is written in Swift and uses Virtualization.framework on Apple silicon.

Looking for command line binaries for running containers?
They are available in the dedicated apple/container repository.

Containerization provides APIs to:

• Manage OCI images.
• Interact with remote registries.
• Create and populate ext4 file systems.
• Interact with the Netlink socket family.
• Create an optimized Linux kernel for fast boot times.
• Spawn lightweight virtual machines and manage the runtime environment.
• Spawn and interact with containerized processes.
• Use Rosetta 2 for running linux/amd64 containers on Apple silicon.

Please view the API documentation for information on the Swift packages that Containerization provides.

Design

Containerization executes each Linux container inside of its own lightweight virtual machine. Clients can create dedicated IP addresses for every container to remove the need for individual port forwarding. Containers achieve sub-second start times using an optimized Linux kernel configuration and a minimal root filesystem with a lightweight init system.

vminitd is a small init system, which is a subproject within Containerization. vminitd is spawned as the initial process inside of the virtual machine and provides a GRPC API over vsock. The API allows the runtime environment to be configured and containerized processes to be launched. vminitd provides I/O, signals, and events to the calling process when a process is run.

Backends

Containerization abstracts the VMM behind the VirtualMachineManager / VirtualMachineInstance protocols and ships two implementations:

• macOS — Virtualization.framework (VZVirtualMachineManager). The shipping path on Apple silicon. Uses Apple's Virtualization framework directly; no extra binaries required.
• Linux — cloud-hypervisor + KVM (CHVirtualMachineManager). One cloud-hypervisor subprocess per VM, controlled over its REST-on-UDS API by the standalone CloudHypervisor Swift package. Block storage uses virtio-blk, shared directories use virtio-fs (one virtiofsd per share), networking uses TAP, and the guest agent is reached over cloud-hypervisor's hybrid vsock — same vminitd contract as the macOS path, so guest-side semantics are unchanged.

The Linux backend requires:

• cloud-hypervisor and virtiofsd on the host. Both are looked up on PATH by default; CHVirtualMachineManager.init accepts explicit URLs to override. virtiofsd is resolved lazily — a VM that uses only block-device mounts can run without it installed at all. Recent stable releases of each are recommended (smoke testing pins specific versions).
• KVM access (/dev/kvm readable + writable by the calling user).
• Pre-staged TAP / bridge / NAT plumbing if the container needs networking. TAPInterface consumes an existing TAP device by name; bringing it up, attaching it to a bridge, and configuring NAT or routing is the caller's responsibility.

The integration test suite (make linux-integration) runs inside an apple/container Linux VM with nested virt enabled (container run --virtualization). The kata kernel fetched by make fetch-default-kernel does not enable KVM, so the integration suite uses the in-repo kernel at kernel/vmlinux-arm64 (or kernel/vmlinuz-x86_64 on x86_64 hosts) instead — build it with make -C kernel before invoking make linux-integration. On Linux the suite runs only the cross-platform scenarios that don't depend on macOS-only types; the full suite remains macOS-only for now.

Requirements

To build the Containerization package, you need:

• Mac with Apple silicon
• macOS 26
• Xcode 26

Older versions of macOS are not supported.

Example Usage

For examples of how to use the libraries' API surface, the cctl executable is a good start. This app is a useful playground for exploring the API. It contains commands that exercise some of the core functionality of the various products, such as:

1. Manipulating OCI images
2. Logging in to container registries
3. Creating root filesystem blocks
4. Running simple Linux containers

Linux kernel

A Linux kernel is required for spawning lightweight virtual machines on macOS. Containerization provides an optimized kernel configuration located in the kernel directory.

This directory includes a containerized build environment to easily compile a kernel for use with Containerization.

The kernel configuration is a minimal set of features to support fast start times and a lightweight environment.

While this configuration will work for the majority of workloads we understand that some will need extra features. To solve this Containerization provides first class APIs to use different kernel configurations and versions on a per container basis. This enables containers to be developed and validated across different kernel versions.

See the README in the kernel directory for instructions on how to compile the optimized kernel.

Kernel Support

Containerization allows user provided kernels but tests functionality starting with kernel version 6.14.9.

Pre-built Kernel

If you wish to consume a pre-built kernel, make sure it has VIRTIO drivers compiled into the kernel (not merely as modules).

The Kata Containers project provides a Linux kernel that is optimized for containers, with all required configuration options enabled. The releases page contains downloadable artifacts, and the image itself (vmlinux.container) can be found in the /opt/kata/share/kata-containers/ directory.

Prepare to build package

Install the recommended version of Xcode.

Set the active developer directory to the installed Xcode (replace <PATH_TO_XCODE>):

sudo xcode-select -s <PATH_TO_XCODE>

The Linux guest init (vminitd/vmexec) is compiled as a static binary inside a Linux container rather than cross-compiled on your Mac, so no Swift toolchain, Swiftly, or Static Linux SDK setup is required on the host. Install the container CLI, which the build uses to compile the guest:

# Install per https://github.com/apple/container, then verify it is on PATH:
container --version

The first build automatically builds the Linux dev image used to compile the guest, which can take a few minutes.

Build the package

Build Containerization from sources:

make all

Test the package

After building, run basic and integration tests:

make test integration

A kernel is required to run integration tests. If you do not have a kernel locally, a default kernel can be fetched using the make fetch-default-kernel target.

Fetching the default kernel only needs to happen after an initial build or after a make clean.

make fetch-default-kernel
make all test integration

Protobufs

Containerization depends on specific versions of grpc-swift and swift-protobuf. You can install them and re-generate RPC interfaces with:

make protos

Building a kernel

If you'd like to build your own kernel please see the instructions in the kernel directory.

Pre-commit hook

Run make pre-commit to install a pre-commit hook that ensures that your changes have correct formatting and license headers when you run git commit.

Documentation

Generate the API documentation for local viewing with:

make docs
make serve-docs

Preview the documentation by running in another terminal:

open http://localhost:8000/containerization/documentation/

Contributing

Contributions to Containerization are welcomed and encouraged. Please see CONTRIBUTING.md for more information.

Project Status

Version 0.1.0 is the first official release of Containerization. Earlier versions have no source stability guarantees.

Because the Containerization library is under active development, source stability is only guaranteed within minor versions (for example, between 0.1.1 and 0.1.2). If you don't want potentially source-breaking package updates, you can specify your package dependency using .upToNextMinorVersion(from: "0.1.0") instead.

Future minor versions of the package may introduce changes to these rules as needed.