Container Build Options in Apple Container: Complete Command Reference

The container build command supports 25+ options including architecture selection (--arch), resource limits (--cpus, --memory), build-time variables (--build-arg), output formats (--output), and secure secrets management (--secret).

The Apple Container project provides a native container builder that wraps Apple's BuildKit implementation. When you invoke the container build sub-command, the BuildCommand class parses these build options to configure the runtime environment, resource allocation, and export behavior. Understanding these container build options allows you to optimize build performance, target specific platforms, and manage sensitive data securely.

Target Platform Selection

Building for specific hardware architectures and operating systems requires precise platform targeting.

Architecture and OS Specification

The --arch (-a) flag adds a specific architecture type such as arm64 or x86_64 to the build. For broader platform control, the --os flag specifies the target operating system (e.g., linux). When you need complete platform specification, the --platform option takes precedence, accepting a string in the format os/arch[/variant] that overrides both --os and --arch individually.

These values are passed directly to BuildKit's platform selection logic in Sources/ContainerCommands/BuildCommand.swift, ensuring the resulting image matches your target environment.

Resource Allocation and Environment

The builder runs inside a containerized environment that consumes host resources. You can fine-tune these allocations to balance build speed against system load.

CPU and Memory Limits

Use --cpus (-c) to allocate CPU cores to the builder container (default: 2). The --memory (-m) flag controls RAM allocation, defaulting to 2048MB and accepting size suffixes like K, M, G, T, or P for larger values. These limits are enforced by BuilderStart.start in Sources/ContainerCommands/Builder/BuilderStart.swift when launching the builder shim.

DNS Configuration

For custom network resolution within the builder, four related options control DNS behavior:

• --dns <ip> – Sets the nameserver IP address in the builder's /etc/resolv.conf
• --dns-search <domain> – Adds search domains for DNS resolution
• --dns-domain <domain> – Specifies the default DNS domain
• --dns-option <option> – Appends extra DNS options such as ndots:5

These settings propagate to the builder container's network configuration, ensuring external resources resolve correctly during the build process.

Build Execution Control

Control how the builder retrieves source images and which stages of multi-stage Dockerfiles execute.

Caching and Image Pulling

The --no-cache flag disables BuildKit's cache layer, forcing all build steps to rerun from scratch. This is useful for verifying that your build process remains reproducible or when you suspect stale cache issues. To ensure you have the latest base image dependencies, use --pull to trigger a fresh pull of base images before building begins.

Multi-Stage Target Selection

When working with multi-stage Dockerfiles, the --target flag limits the build to a specific stage (e.g., --target production). This capability reduces build time and image size when you only need intermediate artifacts or specific build environments.

Input and Output Configuration

Manage how build context enters the system and how finished images are exported.

Build Arguments and Labels

Pass variables into your Dockerfile using --build-arg <key=val>, which maps to ARG statements in your Dockerfile. These arguments are collected into builder.buildArgs and forwarded to BuildKit. Similarly, --label (-l) attaches metadata to the resulting image by translating key-value pairs into BuildKit export metadata.

Secrets Management

The --secret option provides secure build-time data without baking it into image layers. Acceptable formats include id=<key>,env=<ENV_VAR> or id=<key>,src=<local/path>. In Sources/ContainerCommands/BuildCommand.swift, these secrets are mapped to a dictionary and written to temporary files for BuildKit consumption, ensuring sensitive data never appears in the final image history.

Output Formats

The --output (-o) flag controls how the build artifact is exported, supporting three types:

• type=oci (default) – Exports as an OCI-compliant image
• type=tar – Creates a tarball archive
• type=local – Extracts to a local directory

These options are parsed into Builder.BuildExport objects that determine the final storage format of your built image.

Image Tagging and Metadata

Image Naming

The --tag (-t) flag assigns names and references to your built image. You can repeat this flag multiple times to apply multiple tags to a single build. Each tag is parsed using Reference.parse and added to the imageNames collection for the build session.

Progress and Debugging

Monitor build status or suppress output for automation pipelines.

Progress Display

The --progress flag accepts auto, plain, or tty values (default: auto). This setting determines whether a Terminal attaches to the build process for interactive progress bars. For CI/CD pipelines, use --quiet (-q) to disable ProgressBar updates entirely and suppress build output.

Builder Communication

The --vsock-port flag configures the VSOCK port used to communicate with the builder shim (default: 8088). This low-level setting, defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, controls how the client dials the builder via client.dial(id:"buildkit", port:vsockPort).

Practical Examples

Build a simple image with a custom tag:

container build -t my-app:latest .

Build a specific production stage with extra resources and disabled caching:

container build --target production -c 4 -m 4G --no-cache -t prod-app .

Export as a tarball while injecting a secret from an environment variable:

container build --secret apikey,env=API_KEY -o type=tar,dest=app.tar -t my-app .

Build for a specific architecture with custom DNS:

container build --arch arm64 --dns 8.8.8.8 --build-arg VERSION=1.0 -t arm-app .

Summary

• Container build options in the Apple Container project provide granular control over the BuildKit implementation, from platform targeting to resource management.
• Architecture selection uses --arch, --os, and --platform, with the latter taking precedence when multiple flags are present.
• Resource limits specified via --cpus and --memory constrain the builder container's runtime environment through BuilderStart.start.
• Secure builds leverage --secret to inject sensitive data without exposing it in image layers, while --no-cache ensures reproducible builds.
• Output flexibility through the --output flag supports OCI images, tarballs, or local directory extraction via Builder.BuildExport logic.

Frequently Asked Questions

What is the default resource allocation for the container builder?

By default, the builder container receives 2 CPUs and 2048MB of memory when started via BuilderStart.start. You can override these defaults using the --cpus (-c) and --memory (-m) flags, with memory values supporting standard suffixes like G for gigabytes or M for megabytes.

How do I disable caching during a build?

Pass the --no-cache flag to force BuildKit to rerun every build step from scratch, ignoring any previously cached layers. This option sets the noCache flag on the BuildKit request and is useful for verifying build reproducibility or troubleshooting cache-related issues.

Can I specify multiple architectures in a single build command?

While you can add multiple --arch flags to specify target architectures, the platform resolution ultimately depends on BuildKit's capabilities and the --platform specification. The --platform flag accepts a complete platform string like linux/arm64 and takes precedence over individual --os and --arch flags when constructing the target platform.

Where are build secrets stored during the build process?

According to the implementation in Sources/ContainerCommands/BuildCommand.swift, secrets provided via --secret are mapped to a dictionary and written to temporary files that BuildKit can access during the build. These files exist only for the duration of the build process and are not included in the final image layers, ensuring sensitive data remains ephemeral and secure.

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