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

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, 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.

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.

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.

[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 file provides detailed guidance on configuring memory and CPU limits for large builds, while 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 walks through this process in detail.

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

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:

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:

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:

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, docs/container-system-config.md, and 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.

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