# Apple Container Runtime Implementation: Key Components and Architecture

> Explore Apple's container runtime implementation. Learn about its Swift client-server model, XPC communication, Linux VMs, and the Virtualization framework. Understand the core architecture today.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: architecture
- Published: 2026-07-01

---

**Apple's container runtime implementation is built around a Swift-based client-server architecture that uses XPC communication to manage lightweight Linux VMs via the Virtualization framework.**

The [apple/container](https://github.com/apple/container) repository provides a lightweight Linux-VM based container platform designed specifically for macOS. This Apple container runtime implementation separates concerns between service management, client communication, and VM orchestration to provide a secure, extensible container environment.

## Core Components of the Apple Container Runtime

The architecture centers on several key Swift components that handle everything from VM lifecycle management to inter-process communication.

### RuntimeService (Actor)

The **`RuntimeService`** actor serves as the server-side implementation running inside the per-container helper (`container-runtime-linux`). Located in [[`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift), this component creates the Linux VM, configures networking, manages the sandbox lifecycle, and processes XPC requests including bootstrap, start/stop, and file copy operations. It also handles resource cleanup when containers terminate.

### RuntimeClient

The **`RuntimeClient`** provides the client library used by the CLI and other tools to communicate with a running `RuntimeService`. Found in [[`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift)](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift), it builds XPC requests, sends them to the service endpoint, and decodes responses containing sandbox state and process status. This client abstracts the underlying XPC complexity from consumers.

### RuntimeRoutes and RuntimeKeys

Communication between client and server relies on two supporting structures. **`RuntimeRoutes`**, defined in [[`Sources/Services/Runtime/RuntimeClient/RuntimeRoutes.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeRoutes.swift)](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeRoutes.swift), is an enum containing XPC method names such as `bootstrap`, `createProcess`, `stop`, and `copyIn`. **`RuntimeKeys`**, located in [[`Sources/Services/Runtime/RuntimeClient/RuntimeKeys.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeKeys.swift)](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeKeys.swift), defines the keys used inside XPC messages for passing container IDs, process configurations, stdio handles, environment variables, and network bootstrap information.

### ServiceManager

The **`ServiceManager`** handles registration and control of launchd services. Implemented in [[`Sources/ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/ServiceManager.swift)](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/ServiceManager.swift), this helper abstracts `launchctl` commands to start and stop the `container-runtime-linux` helper, which runs as a launchd agent. It manages the service lifecycle independently of the container logic.

### RuntimeConfiguration

Container-specific settings persist through **`RuntimeConfiguration`**, a JSON-serializable structure defined in [[`Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift)](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift). This structure stores paths, kernel configuration, initial filesystem details, and the opaque `runtimeData` payload. The CLI writes this file, and the service reads it to spin up the VM with correct parameters.

### Plugin Infrastructure

Extensibility comes through the plugin system centered on **`PluginLoader`** and `PluginFactory`. Located in [[`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift)](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift), this infrastructure discovers and loads plugins from user- or system-provided directories, enabling support for new runtime types beyond the default Linux sandbox.

## Architecture and Communication Flow

The Apple container runtime implementation follows a strict client-server model orchestrated by the `container` CLI.

1. **Client Initialization**: The CLI creates a `RuntimeClient` using `RuntimeClient.create(id:runtime:)` to establish an XPC endpoint.
2. **VM Bootstrap**: `RuntimeService` receives the request, launches a lightweight Linux VM via the Virtualization framework, and establishes the sandbox environment.
3. **Operation Execution**: The client issues XPC calls using constants from `RuntimeRoutes` and `RuntimeKeys` to create processes, copy files, and manage container state.
4. **State Management**: The service returns JSON-encoded structures like `SandboxSnapshot` containing process status and exit codes.
5. **Cleanup**: When stopping, `RuntimeService` tears down the VM while `ServiceManager` deregisters the launchd service.

## Working with the Runtime Client

The following Swift examples demonstrate typical usage patterns against the Apple container runtime implementation.

### Creating a Client and Bootstrapping

```swift
import ContainerAPIClient
import ContainerResource
import ContainerXPC
import Containerization
import TerminalProgress

// Create a client for a container named "my-app" using the default runtime
let client = try await RuntimeClient.create(id: "my-app", runtime: "linux-sandboxd")

// Prepare stdio handles (nil means inherit from parent)
let stdio: [FileHandle?] = [nil, nil, nil]

// Provide network bootstrap info (empty for first container)
let networkInfos: [NetworkBootstrapInfo] = []

// Launch the VM and start the sandbox
try await client.bootstrap(stdio: stdio, networkBootstrapInfos: networkInfos)

```

### Creating and Running Processes

```swift
// Define process configuration (OCI spec equivalent)
let procConfig = ProcessConfiguration(
    args: ["/bin/sh", "-c", "echo Hello from the container!"],
    env: [:],
    cwd: "/"
)

// Register and start the process
try await client.createProcess("sh-01", config: procConfig, stdio: stdio)
try await client.startProcess("sh-01")

// Wait for completion and check exit code
let snapshot = try await client.state()
print("Process exited with code:", snapshot.exitCode)

```

### Stopping and Querying State

```swift
// Graceful shutdown with 5-second timeout
let stopOptions = ContainerStopOptions(gracePeriod: .seconds(5))
try await client.stop(options: stopOptions)

// Check current sandbox state
let snapshot = try await client.state()
print("Sandbox is in state:", snapshot.state)  // .running, .stopped, etc.

```

## Summary

- **Apple's container runtime implementation** uses a Swift-based client-server architecture with XPC communication.
- **`RuntimeService`** manages VM lifecycle, networking, and sandbox operations as a launchd agent.
- **`RuntimeClient`** provides the Swift API for creating containers, managing processes, and handling I/O.
- **`RuntimeRoutes`** and **`RuntimeKeys`** define the stable XPC protocol between client and server.
- **`ServiceManager`** abstracts launchd integration for starting and stopping the runtime helper.
- **`RuntimeConfiguration`** persists container settings in a JSON format readable by the service.
- The **Containerization** package (external) provides the low-level VM, networking, and filesystem primitives.

## Frequently Asked Questions

### What is the role of RuntimeService in Apple's container runtime?

**`RuntimeService`** is a Swift actor that runs inside the `container-runtime-linux` helper process. It handles the complete lifecycle of Linux VMs created through the Virtualization framework, processes XPC requests from clients, manages sandbox networking, and ensures proper resource cleanup when containers stop.

### How does the container CLI communicate with the runtime service?

The CLI uses **`RuntimeClient`** to establish an XPC connection to the service. It sends requests using method names defined in **`RuntimeRoutes`** (such as `createProcess` or `stop`) with parameters keyed by **`RuntimeKeys`**. The service processes these requests asynchronously and returns JSON-encoded responses.

### Where does the container runtime store its configuration?

Configuration persists in a JSON file defined by **`RuntimeConfiguration`**, located at [`Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeConfiguration.swift). This structure contains paths to kernel images, initial filesystem layers, and opaque runtime data that the service reads when initializing the VM.

### Can the Apple container runtime support custom container types?

Yes, through the **plugin infrastructure** implemented in [`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift). The **`PluginLoader`** discovers and loads plugins from standard directories, allowing the runtime to support new container types beyond the default Linux sandbox via the `PluginFactory` protocol.