What Is the Containerization Package in Apple Container?

The containerization package is the open-source Containerization Swift library that provides the VM-backed Linux container runtime, OCI image handling, and process management for the Apple Container CLI.

The apple/container repository provides a command-line tool for running Linux containers on macOS Apple Silicon. At its core, this tool delegates low-level container, image, and process management to the containerization package—an open-source Swift library that wraps Apple's Virtualization and vmnet frameworks to deliver a high-level, OCI-compatible API.

Defining the Containerization Package

The containerization package is the Containerization Swift library hosted at https://github.com/apple/containerization. According to the apple/container README.md, the container binary "uses the Containerization Swift package for low-level container, image, and process management."

This library implements the VM-backed container abstraction, handling VM creation, filesystem mounting, networking, OCI image handling, and process execution. It exposes Swift types such as LinuxContainer, ContainerConfiguration, DockerImage, and UnixSocketConfiguration that the CLI and server components consume.

Architecture and Integration

Apple Container follows a layered architecture where the containerization package serves as the foundational runtime layer.

Dependency Declaration in Package.swift

The dependency is explicitly declared in the project's manifest. In Package.swift at lines 55-57, the containerization package is pinned as an exact version dependency:

.package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion)),

This declaration ensures the container binary links against a specific version of the containerization library, providing stable APIs for VM management and container lifecycle operations.

Core Components and Services

The containerization package integrates with several architectural components:

• container CLI: Parses user commands (run, build, image push) and calls high-level APIs from ContainerCommands, which imports Containerization to manipulate images and containers.
• container-apiserver: A launch agent that owns the VM and spawns XPC helpers. It uses Containerization to create a LinuxContainer, configure CPU/memory/mounts, and drive lifecycle events.
• XPC helpers (container-runtime-linux, container-core-images, container-network-vmnet): These per-service helpers import Containerization (e.g., import Containerization in RuntimeService.swift at lines 23-27) and call types such as LinuxContainer, Mount, and Process.

Key APIs and Types in the Containerization Package

The containerization package exposes several critical types that abstract macOS virtualization primitives.

LinuxContainer

The LinuxContainer type represents a VM-backed Linux container instance. In Sources/Services/RuntimeLinux/Server/RuntimeService.swift (lines 23-27), the service instantiates this type to manage container lifecycles. The ConfigureContainer helper at lines 80-86 translates high-level ContainerConfiguration objects into low-level LinuxContainer.Configuration fields.

ContainerConfiguration

This struct encapsulates resource limits and system settings including CPU count, memory allocation, mount points, and socket forwarding. It bridges the gap between CLI arguments and Virtualization framework requirements.

OCI Image Handling

The package provides ContainerImage and related types for OCI-compliant image operations. According to Sources/ContainerImagesService/Server/ImagesService.swift (lines 20-24), these APIs support image pull, push, and storage operations using the containerization library's abstractions.

Practical Implementation Examples

Below are minimal Swift snippets demonstrating how Apple Container leverages the containerization package.

Creating a Linux Container

This example reflects the patterns found in RuntimeService.configureContainer:

import Containerization

// 1️⃣ Build a LinuxContainer.Configuration (CPU, memory, mounts, etc.)
var cfg = LinuxContainer.Configuration()
cfg.cpus = 2
cfg.memoryInBytes = 2 * 1024 * 1024 * 1024          // 2 GiB
cfg.mounts = [
    // Map the host rootFS into the container
    Mount(source: URL(filePath: "/path/to/rootfs"), destination: "/"),
]

// 2️⃣ Create a virtual-machine manager (VZVirtualMachineManager is provided by Apple)
let vmm = VZVirtualMachineManager(
    kernel: /* pre‑built VZLinuxBootKernel */,
    initialFilesystem: cfg.mounts[0].asMount,
    rosetta: false,
    logger: Logger(label: "example")
)

// 3️⃣ Build the container
let container = try LinuxContainer(
    id: "example‑container",
    rootfs: cfg.mounts[0].asMount,
    vmm: vmm,
    logger: Logger(label: "container")
) { cfg in
    // Additional low‑level tweaks (e.g., sysctls)
    cfg.sysctl["net.ipv4.ip_forward"] = "1"
}

// 4️⃣ Start the container’s init process
try container.start()

Loading OCI Images

Image handling as implemented in the container commands layer:

import Containerization

// Load an image from a local tarball (or a remote registry)
let image = try ContainerImage(path: URL(filePath: "/tmp/alpine.tar"))

// Access layers and metadata
print("Image name: \(image.name)")
print("Layers count: \(image.manifest.layers.count)")

XPC Communication

The XPC helpers use the containerization package to bridge inter-process communication:

import ContainerXPC
import Containerization

let client = XPCClient(endpoint: xpc_endpoint_create(connection))
let request = XPCMessage()
request.set(key: "command", value: "run")
request.set(key: "image", value: "docker.io/library/alpine:latest")

// Send request to the runtime service
let reply = try await client.send(request)
let containerID = reply.string(key: "containerID")
print("Started container with ID: \(containerID ?? "nil")")

Source File References

Key implementation files that demonstrate containerization package usage:

• Package.swift (lines 55-57): Declares the containerization dependency.
• README.md (lines 6-11): Documents the package's role in low-level container management.
• Sources/Services/RuntimeLinux/Server/RuntimeService.swift (lines 23-27, 80-86): Core runtime service creating and configuring LinuxContainer instances.
• Sources/ContainerCommands/ContainerCommands.swift (lines 4-8): CLI layer importing Containerization for bundle preparation.
• Sources/Services/ContainerImagesService/Server/ImagesService.swift (lines 20-24): Image service demonstrating pull and storage operations.

Summary

• The containerization package is the open-source Containerization Swift library providing the core runtime for Apple Container.
• It wraps Apple's Virtualization and vmnet frameworks to expose OCI-compatible container APIs.
• Key types include LinuxContainer, ContainerConfiguration, and ContainerImage.
• The dependency is declared in Package.swift lines 55-57 and consumed by the CLI, API server, and XPC helpers.
• It handles VM creation, filesystem mounting, networking, and process execution for Linux containers on Apple Silicon.

Frequently Asked Questions

What is the containerization package in Apple Container?

The containerization package is the open-source Containerization Swift library that implements the VM-backed Linux container abstraction. It provides the runtime logic for OCI image handling, VM lifecycle management, and process execution that the container CLI relies on.

How does the Containerization package interact with Apple's Virtualization framework?

The package wraps the VZVirtualMachineManager and related Virtualization framework APIs to create and manage Linux VMs. It translates high-level container configurations into Virtualization framework primitives, handling CPU, memory, and filesystem mount configurations.

Where is the containerization package dependency declared?

The dependency is declared in Package.swift at lines 55-57 using .package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion)). This pins the Apple Container tool to a specific version of the containerization library.

What are the main types exposed by the Containerization package?

The package exposes LinuxContainer for VM management, ContainerConfiguration for resource settings, Mount for filesystem mappings, ContainerImage for OCI image operations, and Process for containerized process execution. These types are imported across the CLI and XPC helper services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}