How to Build the apple/container Project: Complete Guide for Apple Silicon

Build the apple/container project on Apple silicon by running make clean all in the cloned repository after verifying Xcode 26 is set as the active developer directory.

The apple/container repository provides a Swift-based command-line tool that runs OCI-compatible Linux containers on Apple-silicon Macs. Built with the Swift Package Manager (SPM), this project requires specific macOS and Xcode versions to compile the runtime services and CLI binary. This guide covers the complete build process from environment preparation to system-wide installation, based on the source structure defined in Package.swift and the build automation in Makefile.

Prerequisites for Building apple/container

Hardware and Operating System Requirements

Building the apple/container project requires Apple silicon (ARM64) hardware and macOS 15 or newer, with macOS 26 recommended for full compatibility. Verify your architecture and OS version with:

uname -m
sw_vers -productVersion

The vmnet framework used for container networking may fail if you place the repository under ~/Documents or ~/Desktop on macOS 26. Clone the source to a path like ~/projects/container to avoid this limitation, as documented in BUILDING.md.

Development Tools and Xcode Configuration

You must install Xcode 26 or later and set it as the active developer directory. The project declares Swift 6.2 in Package.swift, which ships with Xcode 26:

xcode-select --switch /Applications/Xcode.app
xcode-select -p
swift --version  # Should report "Swift version 6.2"

Clone and Prepare the Repository

Clone the repository from GitHub and navigate to the project root:

git clone https://github.com/apple/container.git
cd container

The repository structure includes:

• Sources/ – Swift source code for the CLI and services
• Tests/ – Unit and integration tests
• docs/ – Technical documentation including technical-overview.md

Build, Test, and Install

Debug Build and Test Suite

Compile the debug version and validate functionality with the full test suite:

make clean
rm -rf test-data
make APP_ROOT=test-data all test integration

The make all command compiles the container binary and helper services into bin/ and libexec/. The make test target runs unit tests, while make integration executes integration tests that exercise the full container stack against an isolated data directory.

Release Build Configuration

For production-grade performance, build with release optimizations:

BUILD_CONFIGURATION=release make clean all test integration

Release builds strip debug symbols and enable compiler optimizations that improve the runtime performance of the container-runtime-linux and container-network-vmnet services.

Generate Protobuf Stubs

If you modify the builder API, regenerate the gRPC Swift code:

make protos

This invokes the grpc-swift compiler via rules defined in Protobuf.Makefile to process the protocol buffer definitions from the container-builder-shim project.

Install System-Wide Binaries

Install the compiled binaries to system directories using:

sudo make install

This copies:

• bin/container → /usr/local/bin/container
• Helper services (e.g., container-runtime-linux, container-network-vmnet) → /usr/local/libexec/

After installation, start the system daemon:

container system start

Optional Development Workflows

Local containerization Package Development

To develop against a local copy of the containerization dependency instead of the remote version:

1. Clone containerization adjacent to the container directory:

   cd ..
   git clone https://github.com/apple/containerization.git

2. Edit Package.swift (lines 56-57) to replace the versioned dependency:

   // Replace this:
   .package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion)),
   
   // With this:
   .package(path: "../containerization"),

3. Update the package resolution and rebuild:

   swift package update containerization
   make clean all
   bin/container system stop
   bin/container system start

Custom Builder Shim Configuration

To test changes in the container-builder-shim project:

1. Clone and build the shim:

   git clone https://github.com/apple/container-builder-shim.git
   cd container-builder-shim
   container build -t builder .
   container rm -f buildkit

2. Configure the container tool to use your custom image by adding to ~/.config/container/config.toml:

   [build]
   image = "builder:latest"

3. Run container build commands normally; the tool will use your local builder image instead of the default.

Debug XPC Helpers

To attach a debugger to XPC services like com.apple.container.container-runtime-linux.test, set the environment variable before restarting the daemon:

export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux.test
container system start

Summary

• Hardware requirement: Apple silicon (ARM64) with macOS 15+ (macOS 26 recommended) is mandatory for building apple/container.
• Build command: make clean all creates debug binaries, while BUILD_CONFIGURATION=release make clean all creates optimized releases.
• Installation: make install copies the container CLI and services to /usr/local/bin and /usr/local/libexec.
• Service management: Use container system start to launch the daemon after installation.
• Local development: Edit Package.swift to point to a local containerization checkout via .package(path: "../containerization").
• Protobuf generation: Run make protos after modifying the builder API to regenerate gRPC stubs.
• Key source files: Sources/CLI/main.swift provides the entry point, while Sources/ContainerBuild/Builder.swift handles the gRPC communication with the builder shim.

Frequently Asked Questions

What macOS version is required to build the apple/container project?

You need macOS 15 or newer to compile the project, though macOS 26 is recommended for full compatibility with the vmnet networking framework. The build process will fail on older versions due to dependencies on modern Apple frameworks and Swift 6.2 toolchain features.

How do I generate protobuf stubs after modifying the builder API?

Run make protos from the repository root. This executes the Protobuf.Makefile rules that invoke grpc-swift on the .proto files from the container-builder-shim project, updating the generated Swift code in the Sources/ directory.

Can I build the apple/container project on Intel Macs?

No. The apple/container project exclusively supports Apple silicon (ARM64) hardware. The codebase relies on ARM64-specific virtualization frameworks and the vmnet implementation that are only available on Apple silicon Macs, as reflected in the platform requirements in Package.swift.

Where are the compiled binaries installed?

The make install command copies the container binary to /usr/local/bin/ and helper services (such as container-runtime-linux and container-network-vmnet) to /usr/local/libexec/. These paths allow the system-wide container service to locate and execute the XPC helpers when you run container system start.

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