# What Is the Role of containerd in Apple’s Container Runtime?

> Discover containerd's role in Apple's container runtime. Learn how it manages OCI images, snapshots, and storage within a Linux VM for macOS virtualization.

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

---

**Apple’s `container` tool embeds `containerd` inside a lightweight Linux VM via the `container-runtime-linux` helper, delegating all OCI image operations, snapshot management, and content storage to containerd’s gRPC services while the Swift-based wrapper handles macOS-specific virtualization integration.**

The `apple/container` repository provides a native container runtime for macOS that leverages standard Linux container technologies through virtualization. At the heart of this architecture lies **containerd**, the industry-standard container runtime that handles the heavy lifting of image management and filesystem operations inside the Linux VM. Understanding how Apple integrates this component reveals why the tool can consume standard OCI images while maintaining deep macOS integration.

## How containerd Powers the Linux VM Runtime

Inside each container’s lightweight Linux VM, the `container-runtime-linux` helper process launches an embedded `containerd` daemon. This architecture allows Apple’s Swift-based stack to delegate complex container operations to a battle-tested OCI runtime rather than reimplementing the specification from scratch.

### Content Store and Image Management

The `containerd` daemon manages all OCI-compatible image operations through its gRPC services. When the Apple container tool pulls or unpacks images, it communicates with endpoints such as `/containerd.services.content.v1.Content/*` to handle layer storage, content addressing, and blob retrieval.

In [`Sources/ContainerBuild/BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildRemoteContentProxy.swift), the Swift code defines the specific containerd services it consumes:

```swift
enum ContentService: String {
    case info     = "/containerd.services.content.v1.Content/Info"
    case readerAt = "/containerd.services.content.v1.Content/ReaderAt"
    case delete   = "/containerd.services.content.v1.Content/Delete"
    // …
}

```

### Snapshot and Filesystem Operations

`containerd`’s snapshotter creates writable layers for container root filesystems. The Swift runtime communicates with the containerd snapshot service via the same gRPC endpoints, allowing the Linux VM to manage filesystem layers while the macOS host coordinates the overall container lifecycle.

### Standard OCI Runtime Interface

By exposing containerd’s runtime API, Apple’s helper complies with the OCI Runtime Specification. The higher-level `container` CLI issues standard `create`, `start`, and `stop` commands that the wrapper translates into containerd operations, ensuring compatibility with existing container workflows and tooling.

## Architecture: The Swift Wrapper and containerd Integration

The `container-runtime-linux` helper serves as a bridge between macOS-specific frameworks (Virtualization, vmnet, XPC, launchd) and the Linux-native containerd services. Rather than modifying containerd itself, Apple’s Swift code starts the daemon and forwards gRPC calls to it.

The helper initialization occurs in [`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift), which launches the `container-runtime-linux` process that embeds and starts containerd.

## Configuration and Default Runtime Handler

The Apple container tool defaults to using the containerd-backed runtime for all container operations. In [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift), the default configuration specifies:

```swift
// In ContainerConfiguration.swift – default runtime handler
public var runtimeHandler: String = "container-runtime-linux"

```

Users can override this when launching containers via the CLI. As defined in [`Sources/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/ContainerAPIService/Client/Flags.swift):

```swift
@Option(name: .long,
        help: "Set the runtime handler for the container (default: container-runtime-linux)")
var runtimeHandler: String?

```

This design ensures that containerd remains the default OCI runtime while allowing flexibility for future runtime implementations.

## Summary

- **containerd runs inside the Linux VM** via the `container-runtime-linux` helper, not on the macOS host directly.
- **gRPC communication** between Swift and containerd enables standard OCI image operations, snapshot management, and content storage.
- **Default configuration** in [`ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/ContainerConfiguration.swift) sets `container-runtime-linux` as the runtime handler, ensuring consistent behavior.
- **File locations**: [`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift) handles helper startup, while [`Sources/ContainerBuild/BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildRemoteContentProxy.swift) defines the containerd service endpoints.

## Frequently Asked Questions

### Does Apple’s container tool run containerd directly on macOS?

No. The `containerd` daemon runs inside a lightweight Linux VM that backs each container. The macOS host communicates with containerd through the `container-runtime-linux` helper, which bridges the gap between macOS virtualization frameworks and the Linux runtime.

### How does the Swift code communicate with containerd?

The Swift code communicates via gRPC to containerd’s exposed services. For example, [`BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/BuildRemoteContentProxy.swift) defines endpoints like `/containerd.services.content.v1.Content/Info` to query image metadata and `/containerd.services.content.v1.Content/ReaderAt` to read content blobs.

### What is the container-runtime-linux helper?

The `container-runtime-linux` helper is a Swift-based wrapper that launches inside the Linux VM. It starts the embedded `containerd` daemon and forwards commands from the macOS host, translating between macOS-specific virtualization APIs and standard OCI runtime operations.

### Which containerd services does Apple’s runtime use?

Apple’s runtime primarily uses containerd’s content service for image layer management, the snapshot service for filesystem layer creation, and the runtime service for container lifecycle operations. These are accessed through standard containerd gRPC endpoints as defined in the OCI specification.