share push and share pull

A teammate asks for the agent you used yesterday. A YAML file in a chat message has no version and no address to pull it from. A registry reference has both, but it does not prove who published the file. Docker Agent pushes agent files to OCI registries the way Docker pushes images.

When you finish this section, you can push an agent file, read its manifest, pull it back, and run it by reference.

Push to a registry

share push: pushes an agent configuration file to an OCI registry. The capture pushed files.yaml, an agent with the filesystem and shell toolsets, to a registry:2 container on localhost:15000:

$ docker-agent share push fixtures/agents/files.yaml localhost:15000/m101/agent:v1
Pushing agent $CAPTURE/fixtures/agents/files.yaml to localhost:15000/m101/agent:v1
Successfully pushed artifact to localhost:15000/m101/agent:v1
[exit 0]

The registry speaks plain HTTP, and the push needed no insecure-registry setting (the capture). Its catalog then listed m101/agent with the tag v1, served as application/vnd.oci.image.manifest.v1+json (the capture).

The manifest

{
  "annotations": {
    "io.docker.agent.version": "v1.149.0",
    "io.docker.cagent.version": "v1.149.0",
    "org.opencontainers.image.created": "<ts>",
    "org.opencontainers.image.description": "OCI artifact containing files.yaml"
  },
  "artifactType": "application/vnd.docker.agent.config.v1+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": "<n>",
    "digest": "sha256:<digest>"
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": "<n>",
      "digest": "sha256:<digest>"
    }
  ],
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "schemaVersion": 2
}

artifactType: the field of an OCI manifest that names what the artifact is. Here it marks a Docker Agent config, while the config and the one layer keep Docker image media types. io.docker.agent.version records the release that pushed the file. io.docker.cagent.version repeats it, because v1.23.3 renamed the annotation and kept the old one for backward compatibility.

A file that the agent reads through instruction_file travels inside the artifact. On push, the file contents go into the artifact, so the published agent needs nothing else. Figure 6.4 shows the push, the manifest, and the two ways back.

--key and --encrypt

The capture pushed without --key, so its manifest carries no proof. The flag arrived in v1.132.0, and it takes a key inline or as a file:// path. With --key, the proof goes into manifest annotations, and the YAML itself is always pushed in clear text. A PEM or OpenSSH key (Ed25519, ECDSA, or RSA) records a signature. Any other value is a symmetric secret of at least 16 bytes and records a MAC.

--encrypt also embeds an encrypted copy of the whole YAML, and Ed25519 keys cannot encrypt. Since v1.138.1 the signature covers an in-toto statement in a DSSE envelope instead of the raw YAML bytes. Neither the help nor this capture names the proof annotations, so this manual does not print them.

On the other side, share pull --key checks the signature or the MAC, or decrypts the copy and compares it. The pull fails when the artifact has no protection or when the check does not pass. Both commands read DOCKER_AGENT_ENCRYPT_KEY in place of the flag.

Pull and run by reference

$ docker-agent share pull localhost:15000/m101/agent:v1 --force  (in work/)
Pulling agent localhost:15000/m101/agent:v1
Agent saved to localhost:15000_m101_agent:v1.yaml
[exit 0]

share pull names the file after the reference, with / replaced by _, and --force overwrites an earlier copy. The pulled YAML is byte for byte the pushed files.yaml (the capture). run takes the reference in place of a path, and the replayed run answered from the registry copy:

$ docker-agent run --exec --last --working-dir fixtures/repo --fake work/cassettes/18-files localhost:15000/m101/agent:v1 …
README.md has 1 line.
[exit 0]

A reference also works as a sub_agents entry. Every docker agent run checks a tag reference against the registry, so pin each one to a digest, myorg/agent@sha256:…, to start from cache. serve api --pull-interval N pulls a reference again every N minutes. For local work, run also takes a plain http://localhost URL to an agent file, with no registry at all.

A private repository needs docker login first. Docker Agent forwards a Docker token by itself only for HTTPS URLs under docker.com, and docker.io is not one of them. So a private Hub repository needs docker login docker.io. Older material points to the agentcatalog namespace on Docker Hub, and v1.116.0 removed the references to that namespace, because it is no longer maintained.