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

> Learn to build and run commands from the apple/container repository. Clone, compile with make all, install, and manage services with container start, run, and build commands.

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

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/TerminalCommand.swift) |
| **Helper Scripts** | Installation and upgrade utilities for end-users | [`scripts/update-container.sh`](https://github.com/apple/container/blob/main/scripts/update-container.sh), [`scripts/install-init.sh`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/Builder.pb.swift) and [`Builder.grpc.swift`](https://github.com/apple/container/blob/main/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`.

```bash

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

```bash
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`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/TerminalCommand.swift) handles all subcommand routing.

### Basic Container Operations

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/apple/container/blob/main/Package.swift)** – Swift Package Manager manifest that declares the `container` executable and its dependencies, including the `containerization` framework.
- **[`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift)** – Core image building implementation that orchestrates the build process.
- **[`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift)** – Loads runtime plugins such as `container-runtime-linux` and `container-network-vmnet`.
- **[`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md)** – Official documentation for compilation steps and protobuf generation.
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Builder.pb.swift) and [`Builder.grpc.swift`](https://github.com/apple/container/blob/main/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.