# How to Configure the Builder VM for Container Image Builds

> Configure your builder VM for container image builds. Use CLI flags for temp changes or edit config.toml for persistent defaults. Streamline your build process today.

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

---

**You can configure the builder VM for container image builds using the `container builder start` CLI flags for temporary changes or by editing `~/.config/container/config.toml` for persistent defaults that apply to every build session.**

The builder VM is a lightweight virtual machine that runs the BuildKit service used by the `container build` command. According to the apple/container source code, you can customize this VM's CPU count, memory allocation, and Rosetta settings through either command-line arguments or a TOML configuration file.

## Default Builder VM Settings

The builder VM defaults are defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) within the `BuildConfig` struct:

```swift
public static let defaultCPUs   = 2
public static let defaultMemory = try! MemorySize("2048MB")
public static let defaultRosetta = true
public static var defaultImage: String {
    let tag = String(cString: get_container_builder_shim_version())
    return "ghcr.io/apple/container-builder-shim/builder:\(tag)"
}

```

*Source:* [[`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift)](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift#L80-L88)

If you never modify the configuration, the builder VM starts with **2 CPUs**, **2 GiB RAM**, Rosetta enabled, and the bundled `container-builder-shim` image.

## Configure the Builder VM via CLI

For temporary changes that apply only to the current session, use the `container builder start` command with flags. This implementation is found in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift).

Start a builder with custom resource limits:

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

```

Available flags include:

- `--cpus` (`-c`) – Number of vCPU cores (default: 2)
- `--memory` (`-m`) – RAM size with K, M, G, T, P suffixes (default: 2048 MiB)

If the builder is already running, you must stop and delete it before applying new limits:

```bash
container builder stop
container builder delete
container builder start --cpus 8 --memory 32g

```

These CLI flags override defaults only for the current builder instance. The next `container build` command will use the newly configured VM.

## Configure the Builder VM via Config File

For persistent defaults that survive across sessions, edit `~/.config/container/config.toml`. The `[build]` table in this TOML file mirrors the `BuildConfig` struct and is parsed by [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift).

Example configuration:

```toml
[build]
rosetta = true          # Enable Rosetta for cross-architecture builds

cpus    = 4             # Default CPU count

memory  = "8g"          # RAM allocation (binary units)

image   = "ghcr.io/apple/container-builder-shim/builder:0.12.0"

```

When you run `container builder start` without explicit `--cpus` or `--memory` flags, the builder reads these values from the TOML file. Changes to this file affect all future builds without requiring additional commands.

## When to Tune Builder VM Resources

You should configure the builder VM when:

- **Building large codebases** – Increase CPU cores and RAM to speed up compilation and image layering in multi-stage builds.
- **Cross-architecture builds** – Disable Rosetta (`rosetta = false`) when targeting only native architectures to free resources.
- **Using custom builder images** – Specify a patched `container-builder-shim` image via the `image` field.

## Complete Build Flow Example

Follow this workflow to configure and use a custom builder VM:

```bash

# 1. Stop and remove any existing builder

container builder stop
container builder delete

# 2. Start a new builder with custom resources

container builder start --cpus 6 --memory 16g \
    --image ghcr.io/apple/container-builder-shim/builder:0.12.0

# 3. Build your image (automatically uses the configured VM)

container build -t my-app .

```

The `container build` command communicates over gRPC to the builder VM you configured, using the specified CPU and memory allocations.

## Summary

- The builder VM defaults to **2 CPUs** and **2 GiB RAM** with Rosetta enabled, as defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift).
- Use **CLI flags** (`--cpus`, `--memory`) with `container builder start` for temporary session-specific configuration.
- Edit **`~/.config/container/config.toml`** under the `[build]` section for persistent defaults across all sessions.
- You must **stop and delete** the existing builder before starting a new one with different resource limits.
- The builder VM runs as a container based on the `container-builder-shim` image specified by `BuildConfig.defaultImage`.

## Frequently Asked Questions

### How do I check the current builder VM configuration?

The `container builder start` command in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) parses CLI flags and creates the builder container, but there is no direct "show config" command. To see the effective configuration, check your `~/.config/container/config.toml` file for persistent settings or review the flags you passed to the last `container builder start` command. The defaults are hardcoded in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) as 2 CPUs and 2048MB memory.

### Can I change the builder VM resources without stopping the current builder?

No. According to the implementation in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) and documented in [`how-to.md`](https://github.com/apple/container/blob/main/how-to.md), you must stop and delete the existing builder container before starting a new one with different resource limits. Run `container builder stop` followed by `container builder delete` (or `container builder rm`), then start a new builder with your desired `--cpus` and `--memory` values.

### What is the difference between the CLI flags and the config file?

**CLI flags** (`--cpus`, `--memory`, `--image`) passed to `container builder start` apply only to the current builder instance and override any config file settings for that session. The **config file** at `~/.config/container/config.toml` provides persistent defaults that apply every time you start a new builder without explicit flags. The CLI implementation falls back to the TOML values when flags are omitted.

### Where is the builder VM image defined and how do I customize it?

The default image is defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) within the `BuildConfig.defaultImage` computed property, which references the `container-builder-shim` version. You can override this via the `--image` flag when running `container builder start` or by setting the `image` key under `[build]` in your [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file. This is useful when you need a patched or specific version of the builder shim.