# How BuildKit Integration Works for Building OCI Images in Apple's Container CLI

> Discover how Apple's container CLI builds OCI images with BuildKit integration. Learn about the lightweight Linux VM, parallel builds, and caching for efficient image creation on Apple Silicon.

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

---

**BuildKit integration in Apple's `container` CLI works by launching a lightweight Linux VM that runs the BuildKit daemon inside a `container-builder-shim` image, enabling parallel, cached builds that produce OCI-compliant images on Apple Silicon.**

Apple's `container` CLI provides native OCI container support on macOS by leveraging **BuildKit**, the same high-performance build engine used by Docker. When you run `container build`, the tool orchestrates a dedicated builder VM that executes your Dockerfile with parallel step processing and intelligent caching. This **BuildKit integration** ensures that every image produced is fully OCI-compliant and ready to run with `container run` or push to any OCI registry.

## BuildKit Architecture Components

The BuildKit integration relies on a multi-layered architecture where the CLI delegates build operations to a specialized VM environment.

### The container build Command

The `container build` command parses CLI flags, prepares the local build context, and forwards the build request to the builder container. According to [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), this command supports flags for multi-architecture builds (`--arch`, `--os`, `--platform`), cache control, and output formatting.

### The Builder VM and Shim

When you initiate a build, the CLI communicates with the **`container-builder-shim`** image (default: `ghcr.io/apple/container-builder-shim/builder:<tag>`) to start a lightweight Linux VM. This VM runs the BuildKit daemon and mounts your build context for processing. Resource limits for this VM—including CPU cores, memory allocation, and Rosetta usage—are configurable via the `[build]` section in `~/.config/container/config.toml`, as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### BuildKit Engine

Inside the VM, **BuildKit** handles the actual image construction. The engine provides parallel step execution, automatic layer caching, and multi-architecture output support. You can target multiple architectures simultaneously (e.g., `arm64` and `amd64`) using the `--arch` flag, allowing you to produce cross-platform images in a single build invocation.

### OCI Image Output

By default, the builder writes images in **OCI format** to the local store. However, you can specify alternative output types using the `--output` flag. Supported formats include `type=tar` for exporting to a tarball or `type=local` for extracting to a directory, as detailed in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).

## Configuring the BuildKit Builder

Builder behavior is controlled through the system configuration file. The `[build]` section in `~/.config/container/config.toml` defines default resource limits and the builder image version.

```toml
[build]
cpus = 8
memory = "16g"
rosetta = false
image = "ghcr.io/apple/container-builder-shim/builder:0.12.0"

```

After modifying this configuration, you must restart the builder for changes to take effect. The [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) file provides detailed guidance on configuring memory and CPU limits for large builds, while [`docs/tutorials/container-system-config-tutorial.md`](https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md) offers step-by-step examples of modifying these settings.

## BuildKit Workflow for OCI Images

The typical workflow involves starting the builder, creating your Dockerfile, and executing the build. The tutorial in [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) walks through this process in detail.

First, ensure the builder VM is running with adequate resources:

```bash
container builder start --cpus 4 --memory 8g

```

If you need to adjust resources later, stop the builder and restart with new parameters. The builder defaults to 2 CPUs and 2 GiB of memory if not specified.

Next, create your Dockerfile in the build context directory. Then execute the build with your desired tags and architectures:

```bash
container build \
  --tag myorg/web-app:latest \
  --arch arm64 --arch amd64 \
  --file Dockerfile \
  .

```

The CLI automatically pulls the builder shim if missing, launches the BuildKit VM, and streams build progress to your terminal. Once complete, verify the image with `container image list` or test it immediately with `container run`.

## Advanced BuildKit Features

### Multi-Stage and Secret-Aware Builds

BuildKit supports advanced Dockerfile features including multi-stage builds and secret mounting. To build only a specific stage while passing secrets and busting the cache:

```bash
container build \
  --target production \
  --no-cache \
  --secret my_secret,id=MY_API_KEY,env=API_KEY \
  -t myorg/web-app:prod .

```

### Exporting to Tarball

To export the resulting image as a tarball rather than storing it locally:

```bash
container build \
  -t myorg/web-app:latest \
  --output type=tar,dest=./web-app.tar \
  .

```

This flexibility allows you to integrate Apple Container builds into existing CI/CD pipelines that expect archived image formats.

## Summary

- **BuildKit integration** runs inside a lightweight Linux VM managed by the `container-builder-shim` image, providing Docker-compatible build performance on Apple Silicon.
- Configure builder resources through the `[build]` section in `~/.config/container/config.toml`, controlling CPU, memory, Rosetta usage, and the shim image version.
- The `container build` command supports multi-architecture outputs (`--arch`, `--platform`), multiple output formats (`--output`), and advanced features like secrets and cache control.
- Source documentation in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), and [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) provides authoritative specifications for all build parameters.

## Frequently Asked Questions

### How do I change the default CPU and memory limits for BuildKit builds?

Edit the `[build]` section in `~/.config/container/config.toml` to set `cpus` and `memory` values, then restart the builder with `container builder stop` followed by `container builder start`. The defaults are 2 CPUs and 2 GiB of memory.

### Can I build images for Intel (amd64) architecture on Apple Silicon using container build?

Yes. Use the `--arch amd64` flag, or specify multiple architectures with `--arch arm64 --arch amd64` to build multi-platform images. BuildKit handles the cross-compilation within the builder VM.

### Where does the container CLI store the BuildKit builder image?

The builder uses the `container-builder-shim` image, defaulting to `ghcr.io/apple/container-builder-shim/builder:<tag>` where the tag mirrors the bundled version (e.g., `0.12.0`). You can override this in the `[build]` section of your config file.

### How do I export a container image as a tarball instead of storing it locally?

Use the `--output` flag with `type=tar` and specify the destination path: `--output type=tar,dest=./myimage.tar`. This creates an OCI-compliant tarball suitable for archiving or transferring to other systems.