Containerization

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

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.
• Manage the runtime environment of virtual machines.
• Spawn and interact with containerized processes.
• Use Rosetta 2 for executing x86_64 processes 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. Provide a dedicated IP address to the container to remove the need for individual port forwarding.

Containers achieve sub-second start times using an optimized Linux kernel configuration and a small 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 ran.

Requirements

You need an Apple silicon Mac to build and run Containerization.

To build the Containerization package, your system needs either:

• macOS 15 or newer and Xcode 17 beta
• macOS 16 Developer Preview.

Applications built using the package will run on macOS Sequoia or later, but the following features are not available on macOS Sequoia:

• Non-isolated container networking - with macOS Sequoia, containers on the same vmnet network cannot communicate with each other
• Paravirtualized GPU support

Build the package

Install Swiftly, Swift, and Static Linux SDK:

make cross-prep

If you use a custom terminal application, you may need to move this command from .zprofile to .zshrc (replace <USERNAME>):

# Added by swiftly
. "/Users/<USERNAME>/.swiftly/env.sh"

Restart the terminal application. Ensure this command returns /Users/<USERNAME>/.swiftly/bin/swift (replace <USERNAME>):

which swift

If you've installed or used a Static Linux SDK previously, you may need to remove older SDK versions from the system (replace <SDK-ID>):

swift sdk list
swift sdk remove <SDK-ID>

Build Containerization from sources and run basic and integration tests:

make all test integration

Visual Studio Code

To make changes to vminitd, we recommend installing the Swift extension for Visual Studio Code.

Set "Swift: Path" in the Settings to /Users/<USERNAME>/.swiftly/bin (replace <USERNAME>) and "Swift: Swift SDK" to x86_64-swift-linux-musl. Restart Visual Studio Code to apply the settings.

Open the folder vminitd. Use "Run Task" - "Show All Tasks..." - "Build All" to build the package.

Protobufs

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

make protos

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/documentation/

Contributing

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