Build images with Docker Bake

The fleet's build graph is data: every artifact under core/,
agents/, benchmarks/, models/, and gateways/ ships a
docker-bake.hcl next to its Dockerfile declaring its build
dependencies (.agents/RULES.md:15). docker buildx bake is the one
canonical build invocation — used identically by humans, the CLI, tests,
and out-of-process consumers (OC in-cluster builds, bakah). This skill
covers building with it and authoring the bake files it reads.

Serves: .agents/RULES.md:15 (build graph is data) and its sub-rules,
.agents/RULES.md:11 (reuse over repetition — fleet-wide variables
declared once), and .agents/RULES.md:8 (clean code — bake files stay
minimal).

The convention for bake itself is below; for bake's own semantics see
the Docker Bake documentation.

Building

1. REGISTRY and TAG are fleet-wide, declared once at the root.
   containers/docker-bake.hcl declares REGISTRY (default
   ghcr.io/exgentic) and TAG (default latest). Per-artifact
   files reference ${REGISTRY}/...:${TAG} and never redeclare them
   (.agents/RULES.md:15, sub-rule b — reuse over repetition). Invoking
   docker buildx bake from the repo root picks up
   containers/docker-bake.hcl; wrappers include it explicitly. Why: one place to
   point the whole fleet at a different registry or tag.

2. Build a single target by name. Target names are
   <category>-<name> (agent-openhands, benchmark-aime,
   model-bifrost); leaf core/ images use their bare
   directory name (agent-base-python, benchmark-base-hf)
   (.agents/RULES.md:15, sub-rule a):

   docker buildx bake benchmark-aime          # build one artifact
   docker buildx bake benchmark-aime --load   # ...and load into the daemon
   TAG=v1.2.0 docker buildx bake agent-openhands --push

3. Compose an eval (benchmark × agent × model). The combination
   Dockerfile takes any benchmark + agent + model + otel + runtime
   bundle and produces an eval image. Its bake target is parameterized;
   concrete combos are composed at call time by chaining every
   dependency's -f file and overriding the image-ref args. Bake merges
   all -f files into one graph. Example —
   aime × openhands × bifrost:

   docker buildx bake \
     -f containers/core/agent-base-python/docker-bake.hcl \
     -f containers/core/benchmark-base-hf/docker-bake.hcl \
     -f containers/core/test-exact-match/docker-bake.hcl \
     -f containers/core/otel/docker-bake.hcl \
     -f containers/core/gosu/docker-bake.hcl \
     -f containers/gateways/bifrost/docker-bake.hcl \
     -f containers/models/bifrost/docker-bake.hcl \
     -f containers/benchmarks/aime/docker-bake.hcl \
     -f containers/agents/openhands/docker-bake.hcl \
     -f containers/core/combination.docker-bake.hcl \
     --set "eval.args.BENCHMARK_IMAGE=ghcr.io/exgentic/benchmarks/aime:latest" \
     --set "eval.args.AGENT_IMAGE=ghcr.io/exgentic/agents/openhands:latest" \
     --set "eval.args.MODEL_IMAGE=ghcr.io/exgentic/models/bifrost:latest" \
     --load eval

   Why so many -f files: each artifact owns exactly one target file
   (sub-rule a), so a combo lists every dependency explicitly. Listing
   ten files by hand is tedious in practice — prefer the wrapper in the
   next step.

4. Prefer the CLI wrapper over hand-chaining -f files. The
   framework's CLI (eval-containers build eval <bench> --agent <agent>)
   and the OC build script wrap the composition in step 3, always
   including the root containers/docker-bake.hcl. Hand-chain -f files only
   when debugging the graph directly. Why: the wrapper is the
   maintained composition; hand-listing drifts as dependencies change.

5. For the whole fleet at a release tag, use the release skill.
   Building and pushing every image with the readiness gate is the
   release skill (.agents/release/SKILL.md), which wraps this one.
   The single-artifact and combo flows above are the local dev loop.

6. Podman note. Bake requires buildx, which podman's docker-compat
   shim doesn't ship. To run a fleet build locally against podman,
   install the real Docker CLI alongside podman, but in practice let CI
   do fleet builds — humans build one thing at a time:

   brew install docker-buildx
   export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')
   docker buildx bake benchmark-aime --print

Authoring a bake file

7. Scaffold new files with the generator, don't hand-write. For a
   new artifact:

   eval-containers gen-bake containers/agents/foo
   # wrote containers/agents/foo/docker-bake.hcl

   The generator parses the artifact's Dockerfile (FROM +
   COPY --from=), emits the bake file in the canonical shape, and
   exits. Re-running on an existing file requires --force. Output
   passes the lint by construction. Why: hand-copying drifts; the
   generator derives the contexts from the real Dockerfile.

8. Follow the minimal template — one target, the full surface. A
   bake file owns its artifact's single target and nothing else
   (.agents/RULES.md:15, sub-rule a). The entire surface:

   target "<category>-<name>" {
     context  = "<category>/<name>"
     contexts = {
       "${REGISTRY}/<dep-category>/<dep-name>" = "target:<dep-target-name>"
       # ... one entry per in-repo FROM / COPY --from=
     }
     args = { HF_TOKEN = HF_TOKEN }   # only if the Dockerfile takes it
     tags = ["${REGISTRY}/<category>/<name>:${TAG}"]
   }

   A leaf core image with no in-repo deps comes in at 4 lines (no
   contexts block). Per-artifact templates by type:

   • Leaf core (core/agent-base-python, core/otel,
     core/entrypoint) — FROM only upstream registries, so no
     contexts:

     target "agent-base-python" {
       context = "core/agent-base-python"
       tags    = ["${REGISTRY}/core/agent-base-python:${TAG}"]
     }

   • Core with one in-repo dep (core/benchmark-base-hf):

     variable "HF_TOKEN" { default = "" }
     
     target "benchmark-base-hf" {
       context  = "core/benchmark-base-hf"
       contexts = { "${REGISTRY}/core/entrypoint:${TAG}" = "target:entrypoint" }
       args     = { HF_TOKEN = HF_TOKEN }
       tags     = ["${REGISTRY}/core/benchmark-base-hf:${TAG}"]
     }

   • Agent (agents/openhands) — extends its runtime base
     (.agents/RULES.md:11, sub-rule a). Per-agent upstream versions
     live in the Dockerfile as ARG AGENT_VERSION=x.y.z
     (.agents/RULES.md:9 — internal version axis), driving the install

     • label, NOT the bake tag; the tag is the framework's container
       version, set fleet-wide via ${TAG}:

     target "agent-openhands" {
       context  = "agents/openhands"
       contexts = { "${REGISTRY}/core/agent-base-python" = "target:agent-base-python" }
       tags     = ["${REGISTRY}/agents/openhands:${TAG}"]
     }

   • Benchmark (benchmarks/aime) — extends a benchmark base and a
     grader (.agents/RULES.md:11, sub-rule b):

     variable "HF_TOKEN" { default = "" }
     
     target "benchmark-aime" {
       context  = "benchmarks/aime"
       contexts = {
         "${REGISTRY}/core/benchmark-base-hf:${TAG}" = "target:benchmark-base-hf"
         "${REGISTRY}/core/test-exact-match:${TAG}"  = "target:test-exact-match"
       }
       args = { HF_TOKEN = HF_TOKEN }
       tags = ["${REGISTRY}/benchmarks/aime:${TAG}"]
     }

   • Gateway (gateways/bifrost) and model
     (models/bifrost) follow the same shape; a model FROMs
     its gateway:

     target "model-bifrost" {
       context  = "models/bifrost"
       contexts = { "${REGISTRY}/gateways/bifrost:${TAG}" = "target:gateway-bifrost" }
       tags     = ["${REGISTRY}/models/bifrost:${TAG}"]
     }

   • Combination (core/combination.docker-bake.hcl) — the only
     parameterized template; image refs come in as
     orchestration-composed variables (.agents/RULES.md:15,
     sub-rule h):

     variable "EVAL_BENCHMARK"     {}   # required
     variable "EVAL_AGENT"         {}   # required
     variable "EVAL_AGENT_VERSION" { default = "" }
     variable "BENCHMARK_IMAGE"    {}
     variable "AGENT_IMAGE"        {}
     variable "MODEL_IMAGE"        {}
     variable "OTEL_IMAGE"         { default = "${REGISTRY}/core/otel:${TAG}" }
     variable "GOSU_IMAGE"         { default = "${REGISTRY}/core/gosu:${TAG}" }
     
     target "eval" {
       context    = "."
       dockerfile = "core/combination.Dockerfile"
       args = {
         BENCHMARK_IMAGE      = BENCHMARK_IMAGE
         AGENT_IMAGE          = AGENT_IMAGE
         AGENT_VERSION        = EVAL_AGENT_VERSION
         MODEL_IMAGE          = MODEL_IMAGE
         OTEL_IMAGE           = OTEL_IMAGE
         GOSU_IMAGE           = GOSU_IMAGE
       }
       tags = ["${REGISTRY}/evals/${EVAL_BENCHMARK}--${EVAL_AGENT}:${TAG}"]
     }

9. Map every in-repo FROM / COPY --from= into contexts. Each
   in-repo dependency MUST appear in the target's contexts, mapping
   the full image reference (${REGISTRY}/...:${TAG}) to the dep's bake
   target (target:<name>) (.agents/RULES.md:15, sub-rule d). This
   is what makes the graph explicit and consumable by every build tool.
   Why: a FROM that isn't in contexts is invisible to the build
   graph — the lint catches the mismatch.

10. Build-time secrets go through args with empty defaults. Pass
    args = { HF_TOKEN = HF_TOKEN } and declare
    variable "HF_TOKEN" { default = "" } only when the Dockerfile
    actually takes that ARG (.agents/RULES.md:15, sub-rules e, g).
    Artifacts that don't need a secret pay no ceremony to declare it
    absent. Why: forwarding an unused arg "just in case" fails the lint.

11. Keep variable hygiene strict. A variable MUST exist for
    exactly one of: a per-build override (REGISTRY, TAG — at root
    only), a build-time secret (HF_TOKEN), or an
    orchestration-composed reference (BENCHMARK_IMAGE, AGENT_IMAGE,
    MODEL_IMAGE in the combo template) (.agents/RULES.md:15,
    sub-rule h). Values that ARE the artifact — target name, context
    directory, the FROM graph shape, the :${TAG} suffix itself —
    MUST be hardcoded. Artifact-scoped variables stay in the artifact's
    own file; fleet-wide ones live at root. Every variable MUST be
    referenced — dead declarations fail the lint. Why: a variable is
    configuration, not a hiding place for artifact identity.

Conciseness conventions (the lint trips on each)

These are normative per .agents/RULES.md:15, sub-rule g (Minimal),
and .agents/RULES.md:8 (clean code). Mechanical enforcement —
every artifact has a valid bake file whose contexts match its
Dockerfile's FROM lines — lives in the build-test catalog
(tests/build/RULES.md).

12. One target per file. A bake file owns its artifact's target and
    nothing else. No grouping targets across artifacts; no multi-target
    files. If you want two targets in one file, you have two artifacts —
    put each in its own directory.

13. No inherits chains. Each target's properties are explicit so
    readers don't trace inheritance graphs across files.

14. No group "default". Always name the target you want.

15. Variables go at the top, scoped tight. variable declarations
    come before the target. Per-artifact files declare only what's
    scoped to them (secrets); REGISTRY and TAG stay at root.

16. No comments restating the rule. This skill and .agents/RULES.md
    are the rule; a per-artifact bake file's existence is its citation.
    No header explaining what bake is.

17. No dockerfile-inline. Always reference the real Dockerfile
    in the artifact's directory; inline Dockerfiles obscure the build.

18. args only for declared build-args. If the Dockerfile takes no
    such ARG, the bake file passes no args value for it.

What goes elsewhere, not in bake files

• Build orchestration (which artifacts to build for a given combo):
  src/build.rs and the CLI.
• Compose runtime topology: each benchmark's compose.yaml.
• K8s runtime topology: the shared Helm chart benchmarks/_chart, selected with --set benchmark=<x> + an optional presets/<x>.yaml for bespoke topology.
• Per-task variant builds (swe-bench's 1000+ tasks): the CLI's
  --task-id flow; not enumerated in bake.
• In-cluster OC builds: a translator that reads bake files and emits
  oc start-build calls; lives under oc/.

References

• .agents/RULES.md:15 — Build graph is data (and its sub-rules a–h).
• Docker Bake documentation
• Bakah (daemonless bake for podman/buildah)
• The release skill (.agents/release/SKILL.md) — the fleet-wide
  tagged push that wraps this skill.
• tests/build/RULES.md — the mechanical bake-alignment
  lint and the build sweep.