Docker

The two-way linking model applies to Docker images just as it does to package ecosystems. An image recommends through metadata baked into the image, and an extension targets the image through a Docker purl.

Docker images have no manifest file, but they carry OCI image labels. AXM reads the recommendation from an org.agentextensions.recommendations label whose value is the JSON-encoded AXM package metadata.

Set the org.agentextensions.recommendations label in your Dockerfile to a JSON array of extension declarations. Each entry is an extension reference (@owner/<type>/<name>):

# Dockerfile
LABEL org.agentextensions.recommendations='[{"ref":"@acme/packs/widget-kit"}]'

Keep recommendations identity-only — omit versionRange. AXM resolves the reference to the newest matching extension version and pins it in the user's axm.lock. Prefer recommending a single pack so you keep one stable reference while its contents evolve. Add a semver versionRange only when your image genuinely pairs with a bounded major line of the extension.

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a Docker purl. The registry host is the namespace and the repository is the name:

// pack.json
{
  "packages": [{ "purl": "pkg:docker/acme/widget-kit" }],
}

A specific image digest can be carried in a purl qualifier, but prefer identity-only references that target the repository rather than one digest.

Default to identity-only. Add a VERS versionRange with the docker scheme only when the extension depends on image contents introduced or removed in a known tag range:

{
  "packages": [
    {
      "purl": "pkg:docker/acme/widget-kit",
      "versionRange": "vers:docker/>=1.0.0|<2.0.0",
    },
  ],
}

When the Docker image recommends an extension through the AgentXM Registry and that extension names the image as a companion via its purl, AXM derives official status for the pair — no extra flag. See Official extensions.

The Docker package-author metadata convention is still being finalized. The OCI label location above is the natural carrier for image metadata; the pkg:docker purl is the stable identity an extension uses to target a repository. Confirm the current shape against the polyglot-examples fixtures before relying on it.