Using BuildKit with container build for builder management in Apple Container

The Apple Container CLI manages a dedicated BuildKit builder container through the container builder sub‑commands, which handle automatic lifecycle operations including start, status checks, stop, and deletion.

The apple/container repository provides a lightweight container runtime that leverages BuildKit for efficient image builds. When you run container build, the system automatically manages a specialized builder container that runs the BuildKit daemon, ensuring reproducible builds while maintaining strict resource control.

Architecture of the BuildKit Builder

The builder management system consists of five core Swift source files that implement the complete lifecycle of the BuildKit container. These components work together to ensure that when you execute container build, a properly configured builder is always available.

BuilderStart.swift

Located at Sources/ContainerCommands/Builder/BuilderStart.swift, this file implements the container builder start command. The implementation performs several critical steps: it pulls the configured BuildKit image, unpacks it, and creates a container with the requested CPU, memory, DNS, and network configuration. The startBuildKit private helper function then boots the container‑builder‑shim binary inside the container, which forwards OCI build requests to the BuildKit daemon via a vsock interface.

BuilderStatus.swift

The Sources/ContainerCommands/Builder/BuilderStatus.swift file handles state inspection through the container builder status command. It queries the Docker‑style API for the buildkit container and formats the snapshot into multiple output formats including table, JSON, YAML, or quiet ID output. The implementation gracefully handles the not‑found case, indicating when no builder currently exists.

BuilderStop.swift

Found in Sources/ContainerCommands/Builder/BuilderStop.swift, this command sends a stop request to the running buildkit container. The implementation treats the not‑found error as a success condition, meaning the command is idempotent—running container builder stop on an already stopped builder exits cleanly without errors.

BuilderDelete.swift

The Sources/ContainerCommands/Builder/BuilderDelete.swift file implements container removal through the container builder delete command. By default, this fails if the builder is still running, but the --force flag overrides this safety check, allowing immediate deletion of active builders.

Builder.swift

The Sources/ContainerCommands/Builder/Builder.swift file serves as the command registry, mapping all four sub‑commands (start, status, stop, delete) under the container builder namespace. This modular structure allows the CLI to treat builder management as a distinct operational domain separate from regular container operations.

Automatic Lifecycle Management

When you invoke container build, the CLI performs a configuration validation check against any existing builder. If the builder is missing, or if its current configuration (CPU count, memory limits, DNS settings, or environment variables) differs from the current request, the system automatically executes the equivalent of container builder stop and container builder delete before creating a fresh builder that matches the new parameters.

This ensures that build environments remain reproducible and that resource limits are strictly enforced. The builder container runs the container‑builder‑shim binary, which is installed inside the BuildKit image and acts as the bridge between the container runtime and the BuildKit daemon.

Practical CLI Usage Examples

Starting the Builder

Create a builder with default resources (2 CPUs, 2 GiB RAM):

container builder start

Specify custom resources and DNS configuration:

container builder start --cpus 4 --memory 4096M \
    --dns 8.8.8.8 \
    --dns-domain example.com \
    --dns-search svc.cluster.local

Checking Builder Status

View detailed status in table format:

container builder status

Output for automation scripts:

container builder status --format json
container builder status --format yaml

Get only the container ID:

container builder status -q

Stopping and Deleting

Stop the builder gracefully:

container builder stop

Delete the stopped builder:

container builder delete

Force deletion of a running builder:

container builder delete --force

Typical Workflow

1. Initialize the builder with container builder start and your desired resource allocation.
2. Execute builds using container build—the CLI automatically reuses the running builder if configuration matches.
3. Clean up resources by stopping or deleting the builder when build operations are complete.

Summary

• The apple/container project uses a dedicated BuildKit builder container managed through the container builder sub‑commands.
• BuilderStart.swift handles image pulling, container creation, and shim initialization via the startBuildKit helper.
• BuilderStatus.swift provides multi‑format state inspection with graceful handling of non‑existent builders.
• BuilderStop.swift and BuilderDelete.swift implement safe shutdown and removal, with optional --force for active containers.
• The container build command automatically recreates the builder if configuration drift is detected, ensuring consistent build environments.

Frequently Asked Questions

How does the BuildKit builder communicate with the container runtime?

The builder uses a container‑builder‑shim binary installed inside the BuildKit image. This shim forwards OCI build requests to the BuildKit daemon through a vsock interface, as implemented in Sources/ContainerCommands/Builder/BuilderStart.swift.

What happens if I run container build without starting a builder first?

The CLI automatically checks for a running BuildKit container when container build is invoked. If no builder exists, or if the existing builder's configuration (CPU, memory, DNS) differs from the current build requirements, the system automatically stops and deletes the old builder before creating a new one with the correct specifications.

Can I change the builder resources without manually deleting it first?

Yes. Simply run container builder start with your new --cpus or --memory values. When you subsequently run container build, the CLI detects the configuration mismatch and automatically recreates the builder with the updated resources. Alternatively, you can explicitly run container builder delete --force followed by container builder start with new parameters.

Why does container builder delete fail without the --force flag?

The deletion command requires the builder to be stopped as a safety measure to prevent accidental termination of active builds. If the builder is running, you must either run container builder stop first, or use container builder delete --force to override the protection, as implemented in Sources/ContainerCommands/Builder/BuilderDelete.swift.

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