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

> Discover the core functionalities of apple/container, an OCI-compatible container platform for macOS. Manage images, control systems, and orchestrate container lifecycles with Swift.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: deep-dive
- Published: 2026-07-06

---

**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:

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

```

CLI usage:

```bash
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`](https://github.com/apple/container/blob/main/ImageList.swift), which supports various output formats including quiet mode for shell scripting:

```swift
// 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:

```bash
container image list --quiet

```

### Pulling and Pushing Images

Image transfer operations use [`ImagePull.swift`](https://github.com/apple/container/blob/main/ImagePull.swift) and [`ImagePush.swift`](https://github.com/apple/container/blob/main/ImagePush.swift) to handle registry communication. The pull implementation normalizes references and returns structured results:

```swift
// 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:

```bash
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`](https://github.com/apple/container/blob/main/ContainerCommand.swift), while specific operations like `container run` wrap the runtime client.

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

```swift
// 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:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/ProgressBar.swift). Structured logging is handled by `ContainerLog` via [`ServiceLogger.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/ImageList.swift) and [`ImagePull.swift`](https://github.com/apple/container/blob/main/ImagePull.swift), and full container lifecycle operations.
- The architecture uses XPC-based communication ([`ContainerXPC/XPCServer.swift`](https://github.com/apple/container/blob/main/ContainerXPC/XPCServer.swift)) and exposes an HTTP/gRPC API ([`APIServer/APIServer.swift`](https://github.com/apple/container/blob/main/APIServer/APIServer.swift)) for runtime coordination.
- Persistent state is maintained in SQLite via [`ContainerPersistence/ConfigurationLoader.swift`](https://github.com/apple/container/blob/main/ContainerPersistence/ConfigurationLoader.swift).
- The CLI provides unified logging via swift-log and visual progress indicators through [`TerminalProgress/ProgressBar.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/XPCServer.swift), implements this layer, while the `ContainerRuntimeLinuxServer` plugin handles Linux-specific runtime bridging via `RuntimeLinuxHelper+Start.swift`.