# How to Configure the BuildKit Builder with Custom Resource Limits in Container > Learn how to configure the BuildKit builder with custom resource limits using command-line flags or the container-system-config.toml file for optimal performance. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-20 --- **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`](https://github.com/apple/container/blob/main/container-system-config.toml) file.** The BuildKit builder in the [apple/container](https://github.com/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: ```bash container builder start --cpus 8 --memory 32g ``` The parsing logic lives in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```toml [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: ```bash container builder stop container builder start ``` ## Verifying Current Resource Allocation To confirm the active resource limits, use the status command: ```bash container builder status ``` This invokes [`Sources/ContainerCommands/Builder/BuilderStatus.swift`](https://github.com/apple/container/blob/main/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: ```swift 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`](https://github.com/apple/container/blob/main/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 --memory ` for one-time overrides. - Set persistent defaults in the `[build]` section of [`container-system-config.toml`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.