{"slug": "docker-push-works-on-ai-agents-now", "title": "`docker push` Works on AI Agents Now", "summary": "Docker Engineering open-sourced Docker Agent, an Apache-2.0 docker CLI plugin written in Go that packages AI agents defined in YAML as OCI artifacts, letting teams push, pull, sign and pin agents by digest to registries like Docker Hub and GitHub Container Registry. Agents run via `docker agent run myorg/agent:tag`, and `--key` signing uses a DSSE envelope over an in-toto statement compatible with cosign. Docker Desktop 4.63+ ships the plugin pre-installed, and it supports OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and local Docker Model Runner endpoints.", "body_md": "`docker push` Works on AI Agents Now\n**Docker Agent** is a `docker` CLI plugin that turns an AI agent into an OCI artifact. You define the agent in YAML, run it with `docker agent run`, then ship it with `docker agent share push` to any OCI-compatible registry, Docker Hub or GitHub Container Registry included. Anyone on the team can then run your agent with `docker agent run myorg/agent:tag` ([Docker Agent docs](https://docker.github.io/docker-agent/)). An **OCI artifact** is the registry packaging format container images already use; here it carries an agent config instead of a filesystem. Push, pull, sign, pin by digest: the same lifecycle a container image has, applied to agents.\n\nI run a small agent on a VM myself: it reads a pitch board, writes a Docker post, and stages it for publishing every morning. Getting that thing reproducible on another machine is exactly the problem this tool attacks, so I read the repo and docs end to end. The pitch board lives in Obsidian, the runs land in a ledger, and the whole setup is YAML plus scripts. The moment an agent has a config file, it wants a package format.\n\nThe problem is real enough to have a name around teams I know: the snowflake agent. The system prompt lives in a note app, the tool list lives in a repo nobody can find, and the one person who understands the setup is on holiday. Sharing means pasting YAML into a chat window and hoping the receiver reassembles it correctly, keys and all. Docker's engineering team open-sourced their answer in [docker/docker-agent](https://github.com/docker/docker-agent). The tagline is direct: \"Build, run, and share AI agents with a declarative YAML config, rich tool ecosystem, and multi-agent orchestration.\"\n\nIn this post:\n\n**Key Takeaways**\n\n**Docker Agent** is an open-source Apache-2.0 `docker` CLI plugin ([repo](https://github.com/docker/docker-agent)); Docker Desktop 4.63+ ships it pre-installed, so `docker agent` works out of the box.- An agent is a YAML file: model, description, instruction, optional toolsets. Multi-agent configs add coordinators, specialists, and handoffs.\n`docker agent share push ./agent.yaml ghcr.io/username/my-agent:v1.0` packages the agent as an OCI artifact; `docker agent run myorg/agent:tag` runs it straight from the registry ([distribution docs](https://docker.github.io/docker-agent/concepts/distribution/)).\n`--key` signs on push and verifies on pull using a DSSE envelope over an in-toto statement, the same ecosystem cosign speaks. Pin digests (`myorg/agent@sha256:...`) when rollback protection matters.\n\nStrip the branding and **Docker Agent** is a builder and runtime for agents, written in Go, that plugs into the docker CLI you already have. The repo describes itself as the \"AI Agent Builder and Runtime by Docker Engineering\" ([docker/docker-agent](https://github.com/docker/docker-agent)). It is unusually active for a young project: over eleven thousand commits, 4.6k stars, and a release cadence that produced v1.152.0 in late October 2026.\n\nInstallation is the part I appreciate most, because it is nothing:\n\n`docker agent` and it works.`brew install docker-agent`, or symlink the binary into `~/.docker/cli-plugins/`.\nA rename happened along the way, which is why older posts call it by a different binary name: in March 2026 the maintainers changed the usage samples to the `docker agent` plugin form. If you find a tutorial referencing the old invocation, it is describing the same tool.\n\nProviders are pluggable, which matters if you have opinions about where your tokens go. The README lists OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, and [Docker Model Runner](https://docs.docker.com/ai/model-runner/) for local models, plus custom OpenAI-compatible endpoints. You need at least one API key set, or a local Model Runner endpoint, before anything interesting happens. The docs walk both paths ([Set Up a Model](https://docker.github.io/docker-agent/getting-started/set-up-a-model/)).\n\nThe README's minimal example is the whole mental model:\n\n```\nagents:\n  root:\n    model: openai/gpt-5-mini\n    description: A helpful AI assistant\n    instruction: |\n      You are a knowledgeable assistant that helps users with various tasks.\n      Be helpful, accurate, and concise in your responses.\n    toolsets:\n      - type: mcp\n        ref: docker:duckduckgo\n```\n\nRun it with `docker agent run agent.yaml`. That is an agent: a model, a description the runtime shows when routing work, an instruction that is the system prompt, and toolsets. The `mcp` toolset type references any [Model Context Protocol](https://modelcontextprotocol.io/) server, and the `docker:duckduckgo` ref is a catalog shorthand for DuckDuckGo search. The examples directory in the repo is a catalog of working configs. It is meant to be read as documentation, not just copied: the [examples README](https://github.com/docker/docker-agent/blob/main/examples/README.md) groups them by the feature they showcase, from bare-minimum agents to remote MCP with OAuth.\n\nTwo details from the run command are worth knowing before your config grows. The `-a <agent>` flag picks a specific agent from a multi-agent file, and `--exec` skips the terminal UI for scripting. There is also `docker agent new` for generating a config interactively instead of writing YAML by hand.\n\nSingle agents hit a wall fast: the model juggles planning, searching, and writing in one context window, and quality slides as the task grows. Docker Agent's answer is multi-agent configuration, documented in detail on the [multi-agent concepts page](https://docker.github.io/docker-agent/concepts/multi-agent/). A coordinator holds the goal; specialists hold the skills.\n\nThere are two shapes, and picking between them is the first real design decision:\n\n| Pattern | What it does | Session shape | Tool | \n|---|---|---|---|\n| **Delegation** (`sub_agents` ) | Parent sends a task to a specialist, blocks, collects the result | Child runs in its own sub-session with a clean task description | `transfer_task` | \n| **Handoff** (`handoffs` ) | The active agent switches; conversation continues | Same session, full history visible to the next agent | `handoff` | \n\nDelegation suits a coordinator that fans work out and synthesizes answers. Handoffs suit pipelines where the conversation itself moves down a chain, and they can form cycles: researcher to summarizer and back to root. The docs are explicit that you can mix both in one config, and that `transfer_task` is always auto-approved, so delegation does not generate permission prompts mid-run.\n\nThe repo's [dev-team.yaml](https://github.com/docker/docker-agent/blob/main/examples/dev-team.yaml) example is a good template, and it is close to what I would actually deploy. A product manager agent at the root, a designer and an engineer below it, and a shared SQLite-backed memory so the team remembers decisions across turns:\n\n```\nagents:\n  root:\n    model: model\n    description: Product Manager - Leads the development team and coordinates iterations\n    instruction: |\n      You are the Product Manager leading a development team...\n      Break down user requirements into small, manageable iterations.\n    sub_agents: [designer, awesome_engineer]\n    toolsets:\n      - type: filesystem\n      - type: think\n      - type: todo\n      - type: memory\n        path: dev_memory.db\n```\n\nEvery agent in that example writes decisions to a shared markdown file, which is the habit that keeps agent runs inspectable after the fact. A related pattern for control freaks: `force_handoff` routes the conversation at the runtime level whenever an agent finishes, bypassing the model's tool-calling entirely, which is how you guarantee a researcher always hands to a reviewer even if the model forgets. For parallel fan-out there is a `background_agents` toolset with run, list, and join calls, so three researchers can run at once and the coordinator waits on all of them.\n\nThere is a sandbox angle here too, and it matters once your agents run anything. A sub-agent with a shell toolset on your host is the same trust problem I covered in [putting your AI agent in a sandbox](https://dev.to/drdocker/your-ai-agent-can-run-rm-rf-put-it-in-a-sandbox-2hfl). Docker Agent meets it halfway with a `--sandbox` flag that confines agent commands to a Docker container, but the packaging story and the isolation story are two separate decisions you make independently.\n\nHere is the part that made me sit up, because it is the sentence I did not expect to type. An agent config packages into an OCI artifact and pushes to any registry you already use ([distribution docs](https://docker.github.io/docker-agent/concepts/distribution/)):\n\n``` bash\n$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest\n$ docker agent share push ./agent.yaml ghcr.io/username/my-agent:v1.0\n```\n\nAnd runs straight from the registry, no separate pull step:\n\n``` bash\n$ docker agent run myorg/agent:tag\n$ docker agent run docker.io/username/dev-team:latest -a developer\n```\n\nThat second command is doing something worth pausing on. It runs a whole multi-agent team from the registry and selects one agent out of the config to talk to. Private registries work after a normal `docker login`. Aliases give you short names: `docker agent alias add coder myorg/coder` and then `docker agent run coder`. The API server mode even supports auto-refresh from a registry reference, repulling every N minutes.\n\nThe practical effect on the snowflake problem is immediate. The artifact your team shares stops being a pasted prompt and becomes `myorg/agent:2026-10-26`, versioned alongside your images, auditable in the registry's history, runnable by the new hire on day one.\n\nIf you have shipped containers for a while, you already know the muscle memory this plugs into. It is the same one I leaned on when I wrote about [making Compose actually wait for Postgres](https://dev.to/drdocker/docker-compose-healthchecks-make-dependson-actually-wait-for-postgres-24bn): the fix only counts when it travels with the repo.\n\nThe same goes for the sandbox habit. Once a teammate pulls your agent and runs it, the question becomes what it is allowed to touch, which is the whole subject of [jailing a coding agent in a microVM](https://dev.to/drdocker/your-ai-agent-can-run-rm-rf-put-it-in-a-sandbox-2hfl). Packaging and isolation are the two halves of shipping agents people can actually trust.\n\nAn agent config is more dangerous than an image in one specific way: it is instructions to a model with tool access. Docker Agent's signing story handles the supply-chain end of that, and it uses the same building blocks as the rest of the ecosystem ([CLI reference](https://docker.github.io/docker-agent/features/cli/)):\n\n``` bash\n$ docker agent share push ./agent.yaml myorg/agent:v1 --key file://~/.ssh/id_ed25519\n$ docker agent share pull myorg/agent:v1 --key file://~/.ssh/id_ed25519.pub\nPulling agent myorg/agent:v1\nVerified signature (ed25519)\nimage: index.docker.io/myorg/agent:v1\ndigest: sha256:889871ef...\ncreated: 2026-09-11T08:30:00Z\n```\n\nThe signature is a **DSSE envelope** over an in-toto Statement v1, stored in the `io.docker.agent.attestation` OCI annotation. **DSSE** (Dead Simple Signing Envelope) is the standard wrapper Sigstore tooling uses for signed statements, which is the point: if you run cosign or in-toto tooling in your pipeline already, the envelope is readable by those tools without Docker Agent involved. The statement's subject binds two things at once: the digest of the agent YAML, and the reference it was published as. That reference binding is why a signed artifact copied to another repository or tag gets rejected on pull.\n\nNow the two honest gaps, straight from the docs, because this is where a naive reading will burn you.\n\nFirst, the YAML is always pushed in clear. Signing proves who published and that the bytes are unaltered; it does not hide the config. If the agent embeds something sensitive, that is what `--encrypt` is for, which records an authenticated encrypted copy of the YAML in the manifest annotations, and it requires a key kind that supports it: symmetric secrets or RSA/ECDSA keys, not bare Ed25519.\n\nSecond, the manifest annotations around the artifact are not authenticated. Anyone with push access to the repository can rewrite the unauthenticated annotations on a signed artifact and the signature still verifies, because the signed statement covers the YAML and the reference, not the descriptive metadata. The docs' guidance is blunt: do not build policy on those annotations; trust the values the pull side prints after verification. And serving an older signed version under the same tag is not detected, since the attestation records the tag, not which version is current. Pin digests when rollback protection matters: `myorg/agent@sha256:4417...` instead of a tag.\n\nThe feature that ties the two halves together is registry references inside a multi-agent config. Your `sub_agents` list can mix locally-defined agents with pulled ones ([multi-agent docs](https://docker.github.io/docker-agent/concepts/multi-agent/)):\n\n```\nagents:\n  root:\n    model: openai/gpt-5\n    description: Coordinator that delegates to local and external sub-agents\n    instruction: |\n      Delegate tasks to the most appropriate sub-agent.\n    sub_agents:\n      - local_helper\n      - myorg/agent:tag   # pulled from registry automatically\n  local_helper:\n    model: openai/gpt-5\n    description: A local helper agent for simple tasks\n    instruction: You are a helpful assistant.\n```\n\nExternal sub-agents are named after their last path segment, or explicitly with `my_reviewer:myorg/reviewer` syntax. Now the interesting part, and the reason pinning matters even for small teams. Tag references are re-resolved against the registry on every `docker agent run`, even when that sub-agent is never invoked in the session. Each unpinned reference is a digest lookup at startup, which the docs measure as a second or two per reference on a healthy connection. It is also one of the paths that stalls outright when the registry or credential helper misbehaves. Pin the digest and the runtime serves the sub-agent from the local cache with no network round-trip, and your team is reproducible by construction. The runtime even logs a startup warning for tag references to nudge you.\n\nThat completes the loop I care about: agents as artifacts, artifacts as team building blocks. A reviewer agent your whole org trusts, versioned and signed, referenced by digest from every team's coordinator.\n\nThree limits worth stating plainly, all from the docs, so you calibrate before betting a workflow on this.\n\nThe signing caveats above are the big ones: clear YAML by default, rewriteable annotations, no rollback detection on tags. If your threat model includes a compromised registry account, digest pinning is not optional.\n\nSecond, scope. This is a builder and runtime, not a fleet-management layer: there is no org-wide policy engine here, no quotas, no audit log beyond what your registry itself gives you. The supply-chain tooling is real, the governance story is your problem. For my one-agent-and-a-ledger setup that is fine; for a bank it is a gap.\n\nThird, the docs at docker.github.io track the main branch and say so on every page, which means some pages describe unreleased features. For stable-behavior claims, cross-check against the repo at the release you run. The config size cap is a concrete number to remember. Agent configurations loaded from HTTP(S) or OCI artifacts are limited to 32 MiB after decompression, which sounds generous until your RAG corpus tries to ride along inside the YAML.\n\nNo. The plugin is pre-installed on Desktop 4.63+, but `brew install docker-agent` or a binary from [GitHub Releases](https://github.com/docker/docker-agent/releases) works anywhere the docker CLI does. Symlink the binary to `~/.docker/cli-plugins/docker-agent` and the `docker agent` invocation is yours.\n\nOnly if you go local: the supported path is [Docker Model Runner](https://docs.docker.com/ai/model-runner/), which serves models on your own machine, and the repo ships a `dmr.yaml` example that wires exactly that. Otherwise the docs are clear that most agents need at least one provider key in the environment.\n\nNo. Sign mode records proof of origin and integrity; the YAML layer itself stays in clear. `--encrypt` exists for confidentiality, needs `--key`, and only works with key kinds that support it: symmetric secrets of at least 16 bytes, or RSA/ECDSA keys. Passphrase-protected keys are not supported at all.\n\nYes, that is the harness feature: a sub-agent defined with a `harness:` block instead of a `model:` runs inside an external coding CLI, and the orchestrator uses `transfer_task` on it like any other specialist.\n\nThe signature on the original artifact does not transfer. A different publisher cannot produce a valid signature for it, and a signed artifact copied to another repository or tag is rejected on pull. What is not prevented is the legitimate key holder republishing older content under the same tag, which is why the docs push digest pinning when rollback protection matters.\n\nEvery team I know has one agent config that started as an experiment and quietly became load-bearing. Mine writes this blog. Yours might triage alerts, review pull requests, or draft changelogs. The packaging story for those finally exists, and it is the one we already use for everything else.\n\nSo, the question: what is the first agent you would `docker agent share push` for your team, and would you sign it? I am genuinely curious what people consider worth packaging, because I suspect the answers say a lot about where the useful agents actually live. Mine is a Docker blogger that lives on a VM and argues with a pitch board every morning. I wrote about [jailing it properly](https://dev.to/drdocker/your-ai-agent-can-run-rm-rf-put-it-in-a-sandbox-2hfl) before I worried about shipping it.\n\n*Verified against the docker/docker-agent repository (README, examples catalog, dev-team.yaml), the Docker Agent docs at docker.github.io (installation, set-up-a-model, multi-agent, distribution, CLI reference), the Docker Model Runner docs, and modelcontextprotocol.io, all retrieved 2026-10-26. Every factual claim links to its source. I did not push a signed agent to a live registry on this machine; each claim traces to the linked documentation, and I flag anything I could not verify.*\n\nEvery claim above traces to these primary sources. Where I could not verify something hands-on, the post says so.\n\nTwo earlier posts in this Docker series set the groundwork for this one:\n\nKunal Das writes operations engineering notes as he learns them, always against primary sources. Contact: [GitHub](https://github.com/kunalworldwide) and [Dev.to](https://dev.to/drdocker). Follow the [Docker tag](https://dev.to/t/docker) for the next posts in this series.", "url": "https://wpnews.pro/news/docker-push-works-on-ai-agents-now", "canonical_source": "https://dev.to/drdocker/docker-push-works-on-ai-agents-now-3k70", "published_at": "2026-10-26 05:02:11+00:00", "updated_at": "2026-10-26 05:13:11.421794+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "mlops", "ai-infrastructure"], "entities": ["Docker", "Docker Engineering", "Docker Agent", "GitHub Container Registry", "Docker Hub", "Docker Model Runner", "OpenAI", "Anthropic"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/docker-push-works-on-ai-agents-now", "markdown": "https://wpnews.pro/news/docker-push-works-on-ai-agents-now.md", "text": "https://wpnews.pro/news/docker-push-works-on-ai-agents-now.txt", "jsonld": "https://wpnews.pro/news/docker-push-works-on-ai-agents-now.jsonld"}}