[Request]: Support Docker/BuildKit named build contexts in container build

[tinovyatkin]

Feature or enhancement request details

container build should support Docker/BuildKit named build contexts, equivalent to Docker/Buildx and Podman --build-context name=value.

This is a Dockerfile/BuildKit feature used by higher-level build tooling to pass additional local directories, Git contexts, URLs, OCI layouts, or image references into a build without copying them under the primary build context. Typical Dockerfile usage is:

FROM alpine
COPY --from=deps /some/file /some/file

with a CLI invocation like:

container build \
  --build-context deps=/path/to/deps \
  -t example:latest \
  .

Today container build --help does not expose --build-context, and the public build RPC/config path appears to carry only one primary context directory. That means tools that rely on named contexts cannot transparently use Apple container as a Docker-compatible builder even though the underlying builder is BuildKit-based.

Why this matters

Named contexts are not only a convenience feature. They are used by libraries and build systems that need to:

• avoid copying large generated/source trees into the main context;
• keep Dockerfile context boundaries explicit;
• consume additional local source roots in monorepos;
• pin or lock base images via docker-image://... contexts;
• match Docker/Buildx and Podman behavior for existing consumers.

For example, AWS CDK-style container asset builders can receive a user-supplied map of build contexts. Without this flag, such libraries must either reject Apple container for those builds or switch to a separate BuildKit path and only load the final OCI image into container afterward.

Existing ecosystem support

Docker/Buildx supports named build contexts:

docker buildx build --build-context deps=/path/to/deps .
docker buildx build --build-context base=docker-image://alpine:latest .

Podman supports the same concept:

podman build --build-context deps=/path/to/deps .
podman build --build-context base=docker-image://alpine:latest .

Direct BuildKit supports the underlying mechanism through Dockerfile frontend options. For local named contexts this is roughly:

buildctl build \
  --frontend=dockerfile.v0 \
  --local context=. \
  --local dockerfile=. \
  --local deps=/path/to/deps \
  --opt context:deps=local:deps

For image/OCI contexts BuildKit frontend attrs use forms such as:

--opt context:base=docker-image://alpine:latest
--opt context:base=oci-layout:/path/to/oci-layout@sha256:...

So the underlying BuildKit machinery already supports this. The missing piece seems to be Apple container CLI/API/shim plumbing for multiple named contexts and the corresponding context transfer/serving logic.

Suggested behavior

Add support for one or more --build-context name=value flags to container build, matching Docker/Podman syntax where practical.

At minimum, support these common values:

• name=/absolute/or/relative/local/path
• name=docker-image://registry/name:tag
• name=docker-image://registry/name@sha256:...
• name=oci-layout:/path/to/layout@sha256:...
• URL/Git contexts if they are already supported by the selected Dockerfile frontend

The local path case likely needs the build request/shim protocol to carry more than the current primary context and expose each named local context to BuildKit as a separate local source.

Current workaround

The practical workaround is to bypass container build, run BuildKit directly with named context frontend options, export an OCI archive, and then load the result into Apple container:

buildctl build ... --output type=oci,dest=image.tar
container image load -i image.tar
container image tag <loaded-ref> example:latest

That works, but it loses the simplicity of container build and requires users/tools to manage a separate BuildKit daemon, auth, cache, and networking behavior.

Code of Conduct

• I agree to follow this project's Code of Conduct