# How to Manage Container Builder Instances Using Start, Status, and Stop Commands

> Master container builder instances with start status and stop commands. Effortlessly manage your BuildKit builder lifecycle and handle resource constraints automatically.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: command-reference
- Published: 2026-07-12

---

**Use the `container builder start`, `container builder status`, and `container builder stop` subcommands to control the BuildKit-based builder container lifecycle, with idempotent operations that handle resource constraints and DNS configuration automatically.**

The `apple/container` repository provides a lightweight Container Builder that wraps BuildKit in a managed container environment. Learning how to manage container builder instances through the CLI ensures you can programmatically control build resources, verify service availability, and gracefully shut down the builder when workloads complete.

## Understanding the Container Builder Architecture

The Container Builder is identified by a fixed container ID defined in [`Sources/ContainerResource/Common/ResourceLabels.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Common/ResourceLabels.swift). All lifecycle commands target the constant `builderContainerId` (value: `"buildkit"`), ensuring consistent state management across start, status, and stop operations.

The three primary subcommands are implemented in separate Swift files under `Sources/ContainerCommands/Builder/`:

- **BuilderStart.swift** – Handles image resolution, container creation, and BuildKit bootstrap
- **BuilderStatus.swift** – Queries runtime state and reports human-readable status
- **BuilderStop.swift** – Executes graceful shutdown via the container runtime

## Starting the Builder with `container builder start`

The `container builder start` command implements idempotent container provisioning in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift). When executed, the `start` method first fetches the builder image referenced by `containerSystemConfig.build.image`, then checks for existing containers via `client.get(id: "buildkit")`.

**Configuration change detection** occurs between lines 71–78: if a running container exists but differs in image, CPU, memory, environment, or DNS settings from the requested configuration, the command automatically stops and deletes the old container before recreating it. If the container is stopped but matches the requested configuration, the command simply restarts the BuildKit process inside the existing container (lines 80–84).

Resource allocation uses the `Parser.resources` helper to convert CLI flags into a `Resources` struct:

```bash
container builder start \
    --cpus 4 \
    --memory 8G \
    --dns-nameserver 8.8.8.8 \
    --dns-search example.com

```

The command attaches the builder to the default vmnet network and mounts `/run` as tmpfs alongside the export directory at `/var/lib/container-builder-shim/exports`. Environment variables `BUILDKIT_COLORS` and `NO_COLOR` are automatically forwarded from the host process.

## Checking Builder State with `container builder status`

Query the builder's runtime state using `container builder status`, implemented in [`Sources/ContainerCommands/Builder/BuilderStatus.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStatus.swift). This command calls `ContainerClient.get(id: "buildkit")` and inspects the `container.status` field to determine whether the builder is running, stopped, or absent.

The output provides clear, actionable feedback:

```bash

# Standard output

container builder status

# → "builder is running" or "builder is not running"

# Script-friendly quiet mode

container builder status --quiet && echo "Running" || echo "Stopped"

```

When the `--quiet` flag is supplied, the command suppresses output when the builder is not running, enabling shell scripts to rely solely on exit codes for state detection.

## Stopping the Builder with `container builder stop`

Gracefully terminate the builder using `container builder stop`, defined in [`Sources/ContainerCommands/Builder/BuilderStop.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStop.swift). This invokes `client.stop(id: "buildkit")` to send a termination signal to the container's init process, allowing BuildKit to complete active builds before shutting down.

The operation is safe to run repeatedly; if the builder is already stopped, the command returns a harmless warning rather than failing. For complete removal after stopping, use the delete command with force:

```bash

# Graceful stop

container builder stop

# Force stop and remove container

container builder delete --force

```

## Programmatic API Usage

For custom tooling, import the `ContainerAPIClient` and `ContainerBuild` modules to manage the builder lifecycle directly:

```swift
import ContainerAPIClient
import ContainerBuild
import Logging

let client = ContainerClient()
let logger = Logger(label: "my.tool")

// Start with specific resources
try await BuilderStart.start(
    cpus: 2,
    memory: "4G",
    log: logger,
    dnsNameservers: [],
    dnsDomain: nil,
    dnsSearchDomains: [],
    dnsOptions: [],
    progressUpdate: { _ in },
    containerSystemConfig: await Application.loadContainerSystemConfig()
)

// Query status
if let container = try? await client.get(id: "buildkit") {
    print("Builder status: \(container.status)")
}

// Stop the builder
try await client.stop(id: "buildkit")

```

The [`Tests/IntegrationTests/Build/BuildFixture.swift`](https://github.com/apple/container/blob/main/Tests/IntegrationTests/Build/BuildFixture.swift) file provides additional reference implementations for `builderStart`, `builderStop`, and `builderDelete` methods used in the test suite.

## Summary

- **Container identification** is fixed to the `"buildkit"` container ID across all commands, ensuring consistent targeting.
- **`container builder start`** provisions or reuses containers, automatically recreating them when resource, DNS, or image configuration changes.
- **`container builder status`** reports runtime state and supports `--quiet` mode for script automation.
- **`container builder stop`** executes graceful shutdowns that are safe to invoke multiple times.
- The architecture ensures **idempotent operations**, preventing duplicate container creation or error conditions on repeated commands.

## Frequently Asked Questions

### What happens if I run `container builder start` when the builder is already running?

According to the implementation in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift), the command compares the existing container's configuration against the requested parameters. If the running container matches the requested CPU, memory, DNS, and image settings, the command succeeds without modification. If configuration differs, it stops and removes the existing container before creating a new one with the updated specifications.

### How does the `container builder status --quiet` flag differ from standard output?

The `--quiet` flag suppresses the "builder is not running" message when the container is absent or stopped, emitting no output to stdout. This allows shell scripts to check the exit code (0 for running, non-zero for not running) without parsing text output, making it ideal for CI/CD pipelines and automation scripts.

### Can I customize the builder image used when starting the container?

Yes, the builder image is determined by the `build.image` property in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift). While the CLI uses the system configuration by default, you can modify the configuration source or use the programmatic API to pass a custom `containerSystemConfig` with a different image reference to `BuilderStart.start()`.

### Is it safe to stop the builder while builds are in progress?

The `client.stop(id:)` method sends a graceful termination signal to the container's init process. Active BuildKit operations should complete before shutdown occurs, though the exact behavior depends on the container runtime's stop signal handling. For immediate termination, the `builder delete --force` command stops and removes the container without waiting for graceful shutdown.