How to Configure the Builder VM for Container Image Builds

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 within the BuildConfig struct:

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/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.

Start a builder with custom resource limits:

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:

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.

Example configuration:

[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:

# 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.
• 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 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 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 and documented in 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 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 file. This is useful when you need a patched or specific version of the builder shim.

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