Core Functionalities of apple/container: OCI-Compatible Container Management on macOS

The apple/container repository provides a complete OCI-compatible container platform for macOS 26, exposing system control, image management, container lifecycle operations, and runtime APIs through a modular Swift-based CLI and library architecture.

The apple/container project implements the official container command-line tool shipping with macOS 26. Built on top of the Containerization Swift package, it delivers a full container platform where a thin CLI front-end maps user commands to underlying Swift libraries. The codebase separates concerns into distinct modules handling everything from OCI registry operations to XPC-based daemon communication.

System Control and Daemon Management

The platform provides system control functionality to start, stop, and configure the background container system daemon. This logic resides in the CLI target within Sources/CLI, where the Swift package generates the executable entry point.

When users execute system commands, the CLI initializes a ContainerSystem instance to manage the daemon lifecycle:

// SystemCommand.run() – part of the CLI target (Sources/CLI)
let system = ContainerSystem()
try await system.start()
print("Container system started")

CLI usage:

container system start

OCI Image Management

The Sources/ContainerCommands/Image/ directory implements comprehensive OCI image management including pull, push, tag, save, load, inspect, list, prune, and delete operations.

Listing and Inspecting Images

Image enumeration occurs in ImageList.swift, which supports various output formats including quiet mode for shell scripting:

// ImageList.run() – snippet from ImageList.swift
if quiet && format == .table {
    for image in images {
        let processedReferenceString = try ClientImage.denormalizeReference(
            image.reference,
            containerSystemConfig: containerSystemConfig
        )
        print(processedReferenceString)          // → prints each image reference
    }
    return
}

Command invocation:

container image list --quiet

Pulling and Pushing Images

Image transfer operations use ImagePull.swift and ImagePush.swift to handle registry communication. The pull implementation normalizes references and returns structured results:

// ImagePull.run() – core logic
let reference = try ClientImage.normalizeReference(imageReference)
let pullResult = try await ClientImage.pull(reference, platform: platform)
print("Pulled: \(pullResult.reference)")

CLI usage for pulling:

container image pull alpine:latest

Container Lifecycle Operations

The Sources/ContainerCommands/Container/ directory contains implementations for running containers, executing commands, viewing logs, and managing container state. The generic command handling is provided by ContainerCommand.swift, while specific operations like container run wrap the runtime client.

Running a container involves creating a specification and invoking the runtime:

// ContainerRun.run() – high‑level wrapper around ContainerRuntimeClient
let spec = ContainerSpec(image: imageRef, command: commandArray, env: envVars)
let container = try await runtime.start(spec: spec)
print("Container \(container.id) started")

CLI usage:

container run --image nginx:alpine --publish 8080:80

Volume and Network Management

Volume Handling

The system supports persistent volumes through Sources/ContainerCommands/Volume/VolumeResource+ListDisplayable.swift. This module provides create, list, prune, and inspect functionality for volumes that containers can mount.

Network Configuration

Virtual network creation and management are handled in Sources/ContainerCommands/Network/NetworkResource+ListDisplayable.swift. This enables creating networks, attaching containers, listing networks, and pruning unused resources.

Runtime Infrastructure and APIs

XPC Communication Layer

The ContainerXPC library provides secure client/server APIs for communication between the CLI and the container runtime. The XPCServer.swift file implements the XPC-based interface that facilitates inter-process communication with the daemon.

HTTP/gRPC API Server

The APIServer target exposes a local HTTP/gRPC API used by the CLI and other tools. Implemented in Sources/APIServer/APIServer.swift, this server handles image, container, and system operations through standardized endpoints.

SQLite Persistence Layer

Configuration and state persistence use the ContainerPersistence library. The ConfigurationLoader.swift entry point manages the SQLite store that retains container, image, and system configuration between daemon restarts.

CLI Architecture and User Experience

Command Structure and Argument Parsing

The CLI uses swift-argument-parser to define sub-commands, flags, and options. The ContainerCommands target (declared in Package.swift lines 31-33) exposes the public library interface that defines the command structure.

Progress Reporting and Logging

Long-running operations display colorful progress bars through the TerminalProgress library, specifically ProgressBar.swift. Structured logging is handled by ContainerLog via ServiceLogger.swift, with backends for OSLog, stderr, and file outputs.

Summary

• apple/container implements a full OCI-compatible container platform for macOS 26 using Swift libraries and a CLI front-end.
• Core functionalities include system daemon control (Sources/CLI), comprehensive image management via ImageList.swift and ImagePull.swift, and full container lifecycle operations.
• The architecture uses XPC-based communication (ContainerXPC/XPCServer.swift) and exposes an HTTP/gRPC API (APIServer/APIServer.swift) for runtime coordination.
• Persistent state is maintained in SQLite via ContainerPersistence/ConfigurationLoader.swift.
• The CLI provides unified logging via swift-log and visual progress indicators through TerminalProgress/ProgressBar.swift.

Frequently Asked Questions

What is the relationship between the container CLI and the ContainerCommands library?

The container executable is a thin front-end that depends on the ContainerCommands library. As defined in Package.swift, the library contains the actual command implementations while the CLI target provides the entry point, enabling the command logic to be reused independently of the executable.

How does apple/container store persistent configuration data?

The platform uses the ContainerPersistence library to store container, image, and system configuration in a local SQLite database. The ConfigurationLoader.swift file handles loading this configuration at daemon startup, ensuring state persists across system restarts.

Is apple/container compatible with standard Docker/OCI images?

Yes. According to the source code in ImagePull.swift and related files, the platform supports OCI-compatible images. It uses standard image reference normalization via ClientImage.normalizeReference() and can pull from and push to any OCI-compliant registry.

What protocol does the container daemon use for internal communication?

The daemon uses XPC (Inter-Process Communication) for secure communication between the CLI and runtime components. The ContainerXPC library, specifically XPCServer.swift, implements this layer, while the ContainerRuntimeLinuxServer plugin handles Linux-specific runtime bridging via RuntimeLinuxHelper+Start.swift.

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