buildx_build
Build container images with BuildKit, supporting multi-platform builds, cache import/export, SBOM/provenance attestations, build secrets, and multi-stage targets. Runs with plain progress output for captured logs.
Instructions
Build an image with BuildKit via docker buildx build.
Replaces the legacy image_build tool when you need any of: multi-platform output
(platforms), modern cache export (cache_from/cache_to), SBOM or provenance
attestations, build secrets, or multi-stage builds with target. Always runs with
--progress=plain so output is captured rather than redrawn on a TTY.
With no local buildx plugin and an ssh:// target, the build runs on that host: a local context
directory is copied there honouring .dockerignore, as are file, build_contexts and secret
paths. Raises RuntimeError in that case for output/cache_to with a filesystem dest=,
cache_from with a local src=, or any ssh= — each would resolve on the remote machine, losing
the output or silently changing the build.
args:
context - Build context: a filesystem path or Git/HTTP URL (verbatim; no ~/glob expansion).
The - stdin-tarball form is NOT supported (stdin isn't forwarded — it'd block
on the server's own stdin); serve a pre-packed tarball over HTTP instead. Copied
to the target host when it names a local directory and there is no local plugin.
tags - Image references to apply (-t, repeatable)
platforms - Target platforms, e.g. ["linux/amd64", "linux/arm64"]
file - Dockerfile path. A relative path resolves against this server's working directory
(buildx's own rule), NOT against context — pass e.g. "ctx/Dockerfile" for a
Dockerfile inside the context directory "ctx".
build_args - Build-time variables (each becomes --build-arg KEY=VALUE)
build_contexts - Additional named build contexts (e.g. {"deps": "./vendor"})
labels - Labels to set on the resulting image (each becomes --label KEY=VALUE)
annotations - OCI manifest annotations (passed verbatim, repeatable)
target - Target build stage to stop at
push - Push the result to the registry (mutually exclusive with load)
load - Load the result into the local image store (single-platform builds only)
output - Custom --output specs (e.g. ["type=tar,dest=out.tar"]). A filesystem dest= is
refused when the build has to run on a remote host; dest=- (stdout) is fine.
no_cache - Do not use cache when building
no_cache_filter - Stage names to exclude from caching
pull - Always attempt to pull a newer version of each base image
cache_from - Cache import specs, e.g. ["type=registry,ref=user/img:cache"]
cache_to - Cache export specs
builder - Override the active builder
sbom - Shorthand for --attest=type=sbom; pass "true" or a config string
provenance - Shorthand for --attest=type=provenance; pass "true", "false", or a config string
attest - Custom attestation specs (repeatable)
secret - Secret specs (e.g. ["id=npmrc,src=/home/user/.npmrc"] or ["id=npmrc,env=NPM_TOKEN"]).
~ in src= is NOT expanded (by this tool or the CLI) — use an absolute path.
ssh - SSH agent socket/key specs (e.g. ["default"], using $SSH_AUTH_SOCK). Refused when
the build has to run on a remote host: the socket read would be that host's.
timeout_seconds - Subprocess timeout (default 1800s)
returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ssh | No | ||
| file | No | ||
| load | No | ||
| pull | No | ||
| push | No | ||
| sbom | No | ||
| tags | No | ||
| attest | No | ||
| labels | No | ||
| output | No | ||
| secret | No | ||
| target | No | ||
| builder | No | ||
| context | Yes | ||
| cache_to | No | ||
| no_cache | No | ||
| platforms | No | ||
| build_args | No | ||
| cache_from | No | ||
| provenance | No | ||
| annotations | No | ||
| build_contexts | No | ||
| no_cache_filter | No | ||
| timeout_seconds | No |