`docker push` Works on AI Agents Now

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

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

The 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. The tagline is direct: "Build, run, and share AI agents with a declarative YAML config, rich tool ecosystem, and multi-agent orchestration."

Strip 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 ). 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.

Installation is the part I appreciate most, because it is nothing:

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

Providers 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 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 ).

The README's minimal example is the whole mental model:

agents: root: model: openai/gpt-5-mini description: A helpful AI assistant instruction: | You are a knowledgeable assistant that helps users with various tasks. Be helpful, accurate, and concise in your responses. toolsets: - type: mcp ref: docker:duckduckgo Enter fullscreen mode Exit fullscreen mode Run 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 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 groups them by the feature they showcase, from bare-minimum agents to remote MCP with OAuth.

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

Single 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. A coordinator holds the goal; specialists hold the skills.

There are two shapes, and picking between them is the first real design decision:

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

The repo's 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:

agents: root: model: model description: Product Manager - Leads the development team and coordinates iterations instruction: | You are the Product Manager leading a development team... Break down user requirements into small, manageable iterations. sub_agents: [ designer, awesome_engineer ] toolsets: - type: filesystem - type: think - type: todo - type: memory path: dev_memory.db Enter fullscreen mode Exit fullscreen mode Every 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.

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

Here 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 ):

$ docker agent share push./agent.yaml docker.io/username/my-agent:latest $ docker agent share push./agent.yaml ghcr.io/username/my-agent:v1.0 Enter fullscreen mode Exit fullscreen mode And runs straight from the registry, no separate pull step:

$ docker agent run myorg/agent:tag $ docker agent run docker.io/username/dev-team:latest -a developer Enter fullscreen mode Exit fullscreen mode That 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.

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

If 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: the fix only counts when it travels with the repo.

The 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. Packaging and isolation are the two halves of shipping agents people can actually trust.

An 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 ):

$ docker agent share push./agent.yaml myorg/agent:v1 --key file://~/.ssh/id_ed25519 $ docker agent share pull myorg/agent:v1 --key file://~/.ssh/id_ed25519.pub Pulling agent myorg/agent:v1 Verified signature (ed25519) image: index.docker.io/myorg/agent:v1 digest: sha256:889871ef... created: 2026-09-11T08:30:00Z Enter fullscreen mode Exit fullscreen mode The 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.

Now the two honest gaps, straight from the docs, because this is where a naive reading will burn you.

First, 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.

Second, 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.

The 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 ):

agents: root: model: openai/gpt-5 description: Coordinator that delegates to local and external sub-agents instruction: | Delegate tasks to the most appropriate sub-agent. sub_agents: - local_helper - myorg/agent:tag # pulled from registry automatically local_helper: model: openai/gpt-5 description: A local helper agent for simple tasks instruction: You are a helpful assistant. Enter fullscreen mode Exit fullscreen mode External 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.

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

Three limits worth stating plainly, all from the docs, so you calibrate before betting a workflow on this.

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

Second, 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.

Third, 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.

No. The plugin is pre-installed on Desktop 4.63+, but brew install docker-agent or a binary from GitHub Releases works anywhere the docker CLI does. Symlink the binary to ~/.docker/cli-plugins/docker-agent and the docker agent invocation is yours.

Only if you go local: the supported path is Docker 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.

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

Yes, 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.

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

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

So, 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 before I worried about shipping it.

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.

Every claim above traces to these primary sources. Where I could not verify something hands-on, the post says so.

Two earlier posts in this Docker series set the groundwork for this one:

Kunal Das writes operations engineering notes as he learns them, always against primary sources. Contact: GitHub and Dev.to. Follow the Docker tag for the next posts in this series.