How to Build and Run Commands from the apple/container Repository

To build and run commands from the apple/container repository, clone the repo, run make all to compile the Swift CLI, optionally run sudo make install to install system-wide, then start services with container system start and invoke commands like container run or container build.

The apple/container repository provides a Swift-based containerization CLI for macOS 15 and later. This guide covers the complete workflow for compiling the tool from source and executing its container commands, with specific references to implementation details found in Package.swift and the Makefile.

Build Architecture and Components

The repository organizes its build system around several key components that work together to produce the container binary and its supporting services.

Component	Role	Source Location
Swift Package	Defines the container CLI, the containerization dependency, and modules like TerminalProgress, ContainerPlugin, and ContainerBuild	Package.swift
Makefile	Orchestrates builds via targets like all, test, integration, install, and protos	Makefile
Builder Shim	Generates gRPC client/server code for image building via protoc and grpc-swift	container-builder-shim
CLI Parser	Implements command-line argument parsing and subcommand routing	Sources/ContainerBuild/TerminalCommand.swift
Helper Scripts	Installation and upgrade utilities for end-users	scripts/update-container.sh, scripts/install-init.sh

The Makefile serves as the primary entry point for compilation. The all target runs swift build with the appropriate configuration, while the install target copies built binaries into /usr/local/bin and /usr/local/libexec.

Step-by-Step Build Instructions

Building the project requires Xcode 26 and macOS 15 or later (macOS 26 is recommended). The active developer directory must be properly set before compilation.

# Clone the repository

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

# Compile the tool (debug build by default)

make all

# Run the test suite to verify the build

make test
make integration

# Install binaries system-wide (requires administrator privileges)

sudo make install

If you only need a quick build for experimentation, you can skip make install and run the binary directly from ./.build/debug/container.

Important: After modifying any .proto files, you must regenerate the gRPC Swift code by running make protos. This target executes protoc and grpc-swift to update Builder.pb.swift and Builder.grpc.swift in the builder shim.

Starting the Container System

Before running container commands, you must start the background services including container-apiserver and helper daemons. The CLI manages these via launchd.

# Start all services and create the default VM and networking

container system start

# Check service status

container system status

If you are upgrading from a previous version, stop the existing services first to avoid conflicts:

container system stop

Running Common Container Commands

Once the system is running, you can invoke the full suite of container commands. The command parser in Sources/ContainerBuild/TerminalCommand.swift handles all subcommand routing.

Basic Container Operations

# Run an interactive shell

container run -it ubuntu:latest /bin/bash

# Run a detached web server with port mapping

container run -d --name web -p 8080:80 nginx:latest

# Automatically remove container after exit

container run --rm alpine:latest echo hello

Image and Build Management

# Build from a Dockerfile in the current directory

container build -t myapp:latest .

# Pull an image from a registry

container image pull alpine:latest

# View system resource usage

container system df

Resource Management

# List all containers (including stopped ones)

container list --all

# Create a custom network

container network create --subnet 192.168.100.0/24 mynet

# Create and mount a persistent volume

container volume create mydata
container run -v mydata:/data busybox

Key Source Files and Implementation

Understanding the source structure helps when debugging or extending the tool:

• Package.swift – Swift Package Manager manifest that declares the container executable and its dependencies, including the containerization framework.
• Sources/ContainerBuild/Builder.swift – Core image building implementation that orchestrates the build process.
• Sources/ContainerPlugin/PluginLoader.swift – Loads runtime plugins such as container-runtime-linux and container-network-vmnet.
• BUILDING.md – Official documentation for compilation steps and protobuf generation.
• docs/command-reference.md – Comprehensive reference for all CLI subcommands and flags.

Summary

• Clone and build the repository using make all, which compiles Swift packages and generates gRPC stubs.
• Install system-wide with sudo make install or run directly from .build/debug/container.
• Start services using container system start before executing any container commands.
• Regenerate protobufs via make protos after modifying .proto files.
• Avoid directories under ~/Documents or ~/Desktop for the build on macOS 26 due to a known vmnet bug.

Frequently Asked Questions

What are the minimum system requirements for building apple/container?

The build requires macOS 15 or later, with macOS 26 recommended, and Xcode 26 with the active developer directory set. The tool is designed specifically for Apple Silicon Macs and uses virtualization frameworks not available on Intel Macs or older macOS versions.

How do I regenerate protobuf code after modifying .proto files?

Run make protos from the repository root. This executes protoc with the grpc-swift plugin to regenerate Builder.pb.swift and Builder.grpc.swift in the builder shim directory. You must do this before rebuilding the project if you have changed the gRPC service definitions.

Can I run the container binary without installing it system-wide?

Yes. After running make all, you can execute the binary directly from ./.build/debug/container without running sudo make install. This is useful for development and testing, though you still need to start the system services with container system start before running container commands.

How do I debug the background services when they fail to start?

Set the environment variable CONTAINER_DEBUG_LAUNCHD_LABEL to the specific launchd label (for example, com.apple.container.container-runtime-linux.test) before running container system start. This attaches the debugger to the service during startup, allowing you to trace initialization failures in the container-apiserver or runtime plugins.

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