# Docker

Recommend AXM extensions from a Docker image and target Docker images from an extension.

The [two-way linking](/docs/package-ecosystems/overview) 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](https://github.com/package-url/purl-spec).

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.

## Recommend extensions from an image

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
# 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.

## Target Docker images from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a Docker [purl](https://github.com/package-url/purl-spec).
The registry host is the namespace and the repository is the name:

```jsonc
// 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.

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `docker` scheme only when the extension depends on image
contents introduced or removed in a known tag range:

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

## Official status

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](/docs/package-ecosystems/overview#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`](https://github.com/agentxm/polyglot-examples) fixtures
> before relying on it.