🚧 Working Draft — agentrc 0.1.0-draft.5 is an evolving specification draft, not a finished standard. Expect breaking changes. Changelog â†’

agentrc tooling

A Go implementation of the agentrc CLI and a BuildKit frontend for the Dockerfile-shaped Agentfile (0.1.0-draft.5): four new keywords — IDENTITY, CAPABILITY, SOP, POLICY — plus an ADD --remote extension, layered on real Dockerfile instructions.

Layout

Why reuse BuildKit’s own Dockerfile compiler?

The spec is explicit that the Agentfile is “Dockerfile-shaped”: everything except the four new keywords keeps exact standard Dockerfile semantics, and “two build paths … MUST produce identical artifacts.” Reimplementing multi-stage builds, ARG scoping, COPY/ADD flag handling, and HEALTHCHECK from scratch would be a large, error-prone undertaking with no upside — BuildKit’s own parser/compiler packages (frontend/dockerfile/parser, frontend/dockerfile/instructions, frontend/dockerfile/dockerfile2llb) are public Go packages built for exactly this. agentrc build (the native CLI path) goes further and literally shells out to docker build through the same frontend image, so identical output is guaranteed by construction rather than by parallel maintenance.

Building

go build -o bin/agentrc ./cmd/agentrc
go build -o bin/agentrc-frontend ./cmd/agentrc-frontend

Using the CLI

./bin/agentrc init                                   # scaffold ./Agentfile
./bin/agentrc lint examples/Agentfile.code-reviewer   # validate
./bin/agentrc lock examples/Agentfile.code-reviewer   # write agentrc.lock (Resolved Manifest)
./bin/agentrc inspect examples/Agentfile.code-reviewer  # local: human-readable summary
./bin/agentrc build examples/Agentfile.code-reviewer -t ghcr.io/org/code-reviewer:1.0
./bin/agentrc push ghcr.io/org/code-reviewer:1.0
./bin/agentrc inspect ghcr.io/org/code-reviewer:1.0   # remote: prints org.agentrc.* labels

agentrc inspect accepts either a local Agentfile path (prints a static summary from the extracted file) or a registry reference (pulls the real, already-built image’s config and prints its org.agentrc.* labels — this is the “review before run” path from profiles/oci-package.md §8).

agentrc build, push, and pull shell out to docker build/push/pull — an agentrc artifact is a completely ordinary OCI image, so there is no custom registry client to maintain; the local Docker/OCI credential store (docker login) is reused automatically.

Using the BuildKit frontend directly

Build and load the frontend image locally first:

docker build -t local/agentrc-frontend:dev -f Dockerfile.frontend .

Then either let agentrc build invoke it (the default --frontend-image is local/agentrc-frontend:dev), or drive it directly:

docker build -f examples/Agentfile.minimal \
  --build-arg BUILDKIT_SYNTAX=local/agentrc-frontend:dev \
  -t hello:dev examples

Once the frontend image is published to a registry, an Agentfile’s first line can be changed to # syntax=<registry>/<repo>/agentrc-frontend:<tag> so plain docker build -f Agentfile . dispatches to it automatically, without --build-arg.

Directive → build-time semantics

Testing

go build ./...
go vet ./...
go test -race ./...

Parser, label, and LLB-translation tests run directly against the real fixtures in examples/Agentfile.*; LLB tests use a fake image-meta-resolver so they never touch the network (the examples reference fictional base images like ghcr.io/acme/pii-redacted-base).

There is no automated end-to-end docker build test in this pass — verify the frontend manually with the commands above once a working Docker + BuildKit setup (e.g. docker buildx) is available. This environment’s Docker CLI plugin was architecture-mismatched (darwin/arm64 client, linux/amd64 daemon) so that step could not be run here.

Known limitations / follow-ups