Where to Find Apple's Container Runtime Source Code: A Complete Guide

Apple's container runtime source code is publicly available in the apple/container GitHub repository, with the core implementation located in RuntimeService.swift (XPC service) and RuntimeClient.swift (client library) within the Sources/Services/ directory.

The apple/container repository contains Apple's open-source implementation of a VM-backed container runtime written in Swift. This runtime enables Linux containers to run inside lightweight virtual machines on macOS, using an XPC-based communication architecture between a system service and client applications.

Core Architecture of the Apple Container Runtime

The runtime follows a client-server architecture where a privileged XPC service manages the VM lifecycle, while a client library provides a type-safe Swift API for container operations.

RuntimeService.swift - The XPC Service Core

The heart of the runtime lives in Sources/Services/RuntimeLinux/Server/RuntimeService.swift. This file implements the XPC service that creates, boots, and manages individual container VMs.

Key responsibilities include:

• Creating the container bundle structure
• Booting the Linux VM with the specified kernel
• Configuring virtual networking interfaces
• Tracking process execution within the sandbox
• Exposing the createEndpoint method for XPC connections

RuntimeClient.swift - The Swift Client API

Located at Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift, this module provides the high-level interface that callers such as the container CLI use to interact with the service.

The client implements methods that map directly to XPC routes:

• bootstrap() - Initializes the VM with networking and filesystem configuration
• state() - Returns the current container status and process ID
• createProcess() - Registers a new process configuration
• startProcess() - Executes a registered process inside the container
• stop() - Terminates the container VM

RuntimeRoutes.swift and RuntimeKeys.swift - XPC Communication Layer

Communication between client and service relies on two supporting files in Sources/Services/Runtime/RuntimeClient/.

RuntimeRoutes.swift defines the enum of string identifiers for each RPC endpoint, including routes for bootstrap, state queries, and process management.

RuntimeKeys.swift centralizes the XPC message key definitions used to exchange data such as endpoints, environment variables, standard IO file handles, and network bootstrap information.

RuntimeConfiguration.swift - Configuration Persistence

Container settings persist in Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift. This struct handles JSON serialization of kernel images, initial filesystem layouts, and network configurations that the service reads at startup.

How the Runtime Components Interact

The runtime stack operates through a defined sequence:

1. RuntimeService creates an XPC endpoint via createEndpoint that clients can discover and connect to.

2. The client (RuntimeClient.create) establishes an XPC connection to this endpoint, then invokes high-level methods.

3. Each method call routes through the RuntimeRoutes enum, with data marshaled using keys from RuntimeKeys.

4. Persistent state (kernel paths, filesystem mounts, network topology) loads from a RuntimeConfiguration JSON file when the service initializes.

Practical Code Examples

Below are minimal Swift snippets demonstrating how consumers interact with the runtime.

Creating a Client and Obtaining an XPC Endpoint

import ContainerXPC
import Containerization

// Asynchronously create a client for a container with ID "my-container"
let client = try await RuntimeClient.create(
    id: "my-container",
    runtime: "linux-sandboxd"
)

Bootstrapping a Container

let stdio: [FileHandle?] = [FileHandle.standardInput,
                            FileHandle.standardOutput,
                            FileHandle.standardError]

let networkInfos: [NetworkBootstrapInfo] = [] // build per-network config

await client.bootstrap(
    stdio: stdio,
    networkBootstrapInfos: networkInfos,
    dynamicEnv: ["PATH": "/usr/bin"]
)

Querying Container State

let snapshot = try await client.state()
print("Sandbox is \(snapshot.state), PID: \(snapshot.processID)")

Managing a Process Inside the Sandbox

// Register a new process
let procConfig = ProcessConfiguration(
    command: ["/bin/bash", "-c", "echo Hello"],
    cwd: "/",
    env: [:]
)
try await client.createProcess("proc-1", config: procConfig, stdio: stdio)

// Start the process
try await client.startProcess("proc-1")

Stopping the Container

let options = ContainerStopOptions(force: true, timeout: .seconds(5))
try await client.stop(options: options)

Summary

• Apple's container runtime is implemented in Swift within the apple/container repository.
• RuntimeService.swift hosts the XPC service that manages VM lifecycle and sandbox creation.
• RuntimeClient.swift provides the Swift API for bootstrap, process management, and state queries.
• XPC communication relies on RuntimeRoutes.swift (route definitions) and RuntimeKeys.swift (message keys).
• Configuration persistence uses RuntimeConfiguration.swift to serialize container settings as JSON.
• All components reside under Sources/Services/RuntimeLinux/ (service) and Sources/Services/Runtime/RuntimeClient/ (client).

Frequently Asked Questions

Where is the main entry point for the container runtime service?

The main entry point is RuntimeService.swift located at Sources/Services/RuntimeLinux/Server/RuntimeService.swift. This file implements the XPC service daemon that creates the VM-backed sandbox, configures networking, and exposes the endpoint that clients connect to.

How does the client communicate with the runtime service?

The client communicates via XPC (Inter-Process Communication). The RuntimeClient class in RuntimeClient.swift establishes a connection to the service's XPC endpoint, then sends messages using route identifiers defined in RuntimeRoutes.swift and data keys from RuntimeKeys.swift.

What format does the runtime use for configuration persistence?

The runtime uses JSON for configuration persistence. The RuntimeConfiguration.swift file defines a serializable struct that stores kernel paths, filesystem configurations, and network settings, which the service reads at startup and writes when configuration changes occur.

Is Apple's container runtime open source?

Yes, Apple's container runtime is open source and available under the apple/container repository on GitHub. The implementation includes the complete Swift source code for the XPC service, client libraries, and command-line tools, allowing developers to inspect, build, and modify the runtime.

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