# Using BuildKit with container build for builder management in Apple Container

> Learn how to manage your container build builder lifecycle with BuildKit and Apple Container CLI's builder subcommands. Automate start, stop, status, and deletion.

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

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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):

```bash
container builder start

```

Specify custom resources and DNS configuration:

```bash
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:

```bash
container builder status

```

Output for automation scripts:

```bash
container builder status --format json
container builder status --format yaml

```

Get only the container ID:

```bash
container builder status -q

```

### Stopping and Deleting

Stop the builder gracefully:

```bash
container builder stop

```

Delete the stopped builder:

```bash
container builder delete

```

Force deletion of a running builder:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderDelete.swift).