How to Configure the BuildKit Builder with Custom Resource Limits in Container

You can configure the BuildKit builder with custom CPU and memory limits using either command-line flags (--cpus and --memory) or by setting persistent defaults in the container-system-config.toml file.

The BuildKit builder in the apple/container repository runs inside a lightweight virtual-machine container. By default, it is provisioned with 2 CPUs and 2 GiB of RAM, but these resource constraints can be overridden to support larger builds or limit resource consumption.

Understanding Default Resource Allocation

By default, the BuildKit builder VM is provisioned with 2 CPUs and 2 GiB of RAM as defined in the ContainerSystemConfig.build structure. These defaults are hardcoded in the system configuration and apply to all new builder instances unless explicitly overridden through CLI options or configuration files.

Method 1: Command-Line Overrides

The fastest way to configure custom resource limits is passing flags directly to the container builder start command.

Using the --cpus and --memory Flags

When starting the builder, use the --cpus (or -c) and --memory (or -m) flags to specify exact resource requirements:

container builder start --cpus 8 --memory 32g

The parsing logic lives in Sources/ContainerCommands/Builder/BuilderStart.swift. Specifically, the BuilderStart.start method handles argument parsing at lines 40-51 and 126-133, where the Parser.resources helper converts user-supplied strings into a ContainerResources object. If the builder is already running with different allocations, the system automatically stops and deletes the existing VM before creating a new one with the updated limits.

Method 2: Persistent Configuration

For permanent changes that apply to every builder invocation, modify the container-system-config.toml file.

Editing container-system-config.toml

The [build] table in your configuration file contains cpus and memory entries that override the hardcoded defaults:

[build]
cpus   = 4
memory = "4096mb"

The Application.loadContainerSystemConfig() method reads these values during BuilderStart.run execution. After editing the configuration file—typically located at ~/.config/container/container-system-config.toml—restart the builder to apply changes:

container builder stop
container builder start

Verifying Current Resource Allocation

To confirm the active resource limits, use the status command:

container builder status

This invokes Sources/ContainerCommands/Builder/BuilderStatus.swift to display the current VM details:

ID       IMAGE                                 CPUS   MEMORY
buildkit ghcr.io/apple/container-builder-shim/builder:0.12.0   6      16384MB

Programmatic Configuration (Swift)

When integrating with Swift applications, set the resource properties directly on the BuilderStart struct:

let builder = BuilderStart()
builder.cpus = 4               // optional Int64
builder.memory = "8192mb"      // optional String
try await builder.run()

The Parser.resources helper (called at line 126 in BuilderStart.swift) handles the conversion to a ContainerResources object before VM creation.

Summary

• The BuildKit builder defaults to 2 CPUs and 2 GiB of RAM unless configured otherwise.
• Use container builder start --cpus <n> --memory <size> for one-time overrides.
• Set persistent defaults in the [build] section of container-system-config.toml.
• Changes to resource limits require a builder restart; the system automatically recreates the VM if resources differ from the current allocation.
• Verify active limits with container builder status.
• Swift developers can configure resources programmatically via the BuilderStart struct.

Frequently Asked Questions

What are the default CPU and memory limits for the BuildKit builder?

The BuildKit builder is provisioned with 2 CPUs and 2 GiB of RAM by default. These values are defined in ContainerSystemConfig.build and apply when no overrides are specified via CLI flags or configuration files.

Do I need to restart the builder after changing resource limits?

Yes. If you modify the container-system-config.toml file or want to apply different CLI flags, you must stop and restart the builder. The system detects resource mismatches in BuilderStart.start and automatically recreates the VM when the requested limits differ from the current allocation.

Can I use different units when specifying memory limits?

Yes. The Parser.resources helper in BuilderStart.swift accepts various memory units. You can specify values like "4096mb", "32g", or similar human-readable formats, which are converted into the appropriate ContainerResources values before VM creation.

Where is the container-system-config.toml file located?

The configuration file is typically located at ~/.config/container/container-system-config.toml on Unix systems. You can locate the exact path for your installation by running container system config edit, which opens the file in your default editor.

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