Docker Agent and UHP

Choose the direction before configuring a protocol

Docker Agent can consume external tools, expose agents as tools, or communicate with another agent/client. Those directions need different setup even when the same YAML-defined agent is involved. The current project README distinguishes a preinstalled Docker Desktop 4.63+ CLI plugin from separate installation paths.

You want to	Boundary to configure	What success looks like
Give an agent external tools	MCP client/tool configuration	A real tool result under the selected agent’s policy
Let a tool-using host invoke your agent	Docker Agent MCP server mode	The host discovers and calls the exported agent tool
Give another agent your task service	A2A server/client configuration	Task/message/artifact lifecycle through A2A
Embed an interactive host	ACP	Negotiated client capabilities and permissions
Run a packaged YAML agent locally	docker agent run agent.yaml	The configured model/tool loop reaches its intended result

Start with the README’s declarative YAML structure, using a model available through your provider and only the tools your fixture needs. Keep provider credentials in the approved environment. OCI packaging makes agent definitions portable; it does not carry permission to use another machine’s filesystem, accounts or credentials.

The latest repository release v1.145.0 adds W3C trace propagation through ACP, but a shared trace identifier does not merge the ACP session, A2A task and internal harness conversation. Record their relationship rather than assuming they are one lifecycle.

For a delegated coding harness, decide who owns cancellation, its process and persistent files before nesting it. Harness composition explains that responsibility; UHP vs ACP helps place a host interface beside a product execution API. Neither external Codex/Pi delegation nor native MCP/A2A/ACP support establishes Docker Agent-native UHP support.

Release check — 4 October 2026

The latest stable release observed in the upstream GitHub release API is v1.145.0, published 2026-09-28. This release propagates W3C trace context through ACP requests and fixes lean-TUI scrollback during partial tool calls. Trace propagation is runtime observability, not a new UHP or ACP execution contract.

Evidence scope: the integration details, commands, measurements and development-head references below preserve the 9 Sep 2026 source snapshot. They are not presented as a fresh test of this newer release. For the current UHP protocol, HarnessRouter release and suite coordinates, use the release tracker and conformance guide. Adapter support does not establish upstream-native UHP adoption.

Source snapshot — 9 Sep 2026

Docker Agent is a distinct agent runtime and orchestration layer, not a UHP implementation. Docker describes it as a Docker CLI plugin for defining agents in declarative YAML, running multi-agent teams, attaching tools and models, and packaging agents through OCI registries.

The latest observed stable release is v1.137.0, published 9 September 2026 at 14:24:40 UTC, with tag target cfcca04b03ee829e9fd383bcc1e60fda65178ec1. Checked upstream main is 56473dca0ab1fdc71351d6b39f4b4b420f5844cf at this cutoff, one merged feature commit beyond the release tag.

Stable v1.137.0 removes the session_plan toolset, adds per-model audio/video input filtering and image-output capability handling, rejects incompatible image-output/tool-schema combinations before dispatch, adds the add_context hook, makes rewrite-capable hook stages execute sequentially, and expands shell safety classification. The post-release main commit adds provider-agnostic generated-media deltas to the runtime stream path, but upstream explicitly says that work is not yet progressive image display, remote binary streaming, persistence or TUI delivery.

Caution

No native UHP adoption is established. Reviewed Docker Agent primary sources do not name the Unified Harness Protocol, and HarnessRouter v0.15.7 does not list Docker Agent among its ten released backends. Docker Agent’s native MCP, A2A and ACP surfaces are real interoperability features, but they must not be reclassified as UHP support or UHP conformance.

Why Docker Agent matters to harness interoperability

Docker Agent is unusually relevant because the same runtime exposes several neighboring boundaries at once:

• agent runtime: models, tools, memory, RAG, hooks, permissions and multi-agent delegation;
• coding harness orchestration: external Claude Code, Codex, OpenCode or Pi CLIs can act as harness-backed subagents;
• MCP server: agents can be exposed as MCP tools over stdio or streaming HTTP;
• A2A server and client/tool path: agents can be exposed over A2A and can call remote A2A agents;
• ACP server: a Docker Agent can be embedded by an ACP host over stdio;
• distribution: declarative agent configurations can be pushed to and loaded from OCI registries.

That makes Docker Agent a useful case study in why protocol labels need precise directionality. A single product can be an MCP server, an A2A participant, an ACP agent process and a host for other coding harnesses without implementing UHP.

Coding harnesses inside Docker Agent

Docker Agent’s stable coding-harness feature delegates an agent’s work to an external coding CLI instead of directly calling a model API. Stable v1.137.0 documents four harness types:

Docker Agent harness type	External runtime	Boundary
claude-code	claude	Docker Agent orchestrates; Claude Code owns its coding loop and authentication.
codex	codex	Docker Agent delegates the subagent turn to Codex.
opencode	opencode	OpenCode owns the external coding loop.
pi	pi	Pi is launched as the external coding harness.

The external CLI manages its own model selection and tools. Docker Agent’s ordinary toolsets: are not injected into a harness-backed agent, and Docker Agent’s model-routing pipeline does not control the harness CLI’s model path. Hooks still wrap the delegated run, so Docker Agent retains orchestration/audit policy around a loop it does not itself execute.

This architecture is adjacent to HarnessRouter but materially different. HarnessRouter presents supported harnesses behind a UHP server. Docker Agent instead composes coding CLIs as subagents inside its own orchestration system. Reviewed sources do not establish a HarnessRouter adapter for Docker Agent or a Docker Agent UHP endpoint.

Permission boundary

Docker’s stable harness documentation includes an important operational warning for Claude Code: Docker Agent invokes the CLI non-interactively with --dangerously-skip-permissions. Docker recommends trusted repositories and isolation such as an isolated git worktree. Docker Agent also states that run --sandbox does not automatically make the external CLI or its login available inside the sandbox.

That distinction matters when comparing harnesses: orchestration, approval policy and sandbox placement are implementation concerns unless a protocol explicitly standardizes them.

MCP: expose agents as tools

docker agent serve mcp exposes Docker Agent agents as MCP tools. Stable documentation supports stdio by default and streaming HTTP with --http.

For HTTP, Docker Agent documents the MCP 2026-07-28 stateless model: modern clients use server/discover, no Mcp-Session-Id is issued, and the HTTP server accepts POST while standalone GET/DELETE session behavior is not provided. Older initialize clients remain supported through a compatibility path, but older stateful clients relying on GET streams or session DELETE teardown need to upgrade or switch to a compatible transport.

Non-loopback HTTP requires a bearer token unless the operator explicitly selects the insecure override. This is a Docker Agent security control around its MCP server; it is not part of UHP conformance.

A2A: expose agents to other agents

docker agent serve a2a exposes a configured agent over the Agent2Agent protocol. Stable v1.137.0 documentation calls this support early and documents limitations: tool calls remain internal rather than becoming separate A2A events, artifacts and memory are not yet integrated, and multi-agent/subagent scenarios still need further work.

The stable server defaults to loopback. Non-loopback listeners require --auth-token unless --insecure-no-auth explicitly acknowledges the exposure. Tool safety defaults to restricted; an autonomous safety policy requires an explicit CLI opt-in.

Docker Agent also has an A2A toolset for connecting to remote A2A agents. That is separate from exposing the local Docker Agent as an A2A server.

ACP: embed Docker Agent in a host

docker agent serve acp starts an Agent Client Protocol server over stdio for hosts such as editors or developer tools. Stable documentation says sessions are persisted in SQLite so they can survive process restarts.

The ACP surface supports configured Docker Agent tools, multi-agent delegation and model fallbacks, but the stable documentation explicitly says client-supplied MCP servers are not supported through the ACP session boundary. Persisted sessions use session/resume, not session/load.

Docker’s own documentation summarizes the intended separation well: ACP connects a host application to an agent process, A2A connects agents over the network, and MCP exposes agents as tools. UHP is a fourth boundary: client → UHP server → configured harness. Similar words such as session, tool or agent should not be assumed to have identical semantics across them.

Protocol-direction map

Layer	Verified Docker Agent relationship	UHP relationship
Docker Agent runtime	Native multi-agent runtime/orchestrator with YAML, tools, models, hooks and OCI distribution.	Adjacent harness/runtime architecture.
Coding harnesses	Native delegation to Claude Code, Codex, OpenCode and Pi.	Not a UHP adapter; external CLIs remain their own runtimes.
MCP	Native server mode exposes Docker Agent agents as tools; Docker Agent can also consume MCP toolsets.	Separate tool/context interoperability boundary.
A2A	Native server plus remote-agent tool path; stable support marked early.	Separate agent-to-agent boundary.
ACP	Native stdio server for host/editor embedding.	Separate client/editor-to-agent boundary.
UHP	Not established in reviewed Docker Agent sources.	No native adoption or conformance evidence.
HarnessRouter	Docker Agent is not in the released ten-backend set at this cutoff.	No released adapter evidence.

v1.137.0 release boundary

Stable v1.137.0 is a material harness-runtime release, but it does not change MCP, A2A, ACP or UHP protocol versions.

• Planning surface: the release removes the session_plan toolset, including its handlers, stream event, plans service and TUI /plans browser. This is a Docker Agent internal tool/runtime breaking change rather than a protocol-level task or session change.
• Multimodal capability gating: request handling now detects model audio/video input support, strips unsupported media while preserving provider-specific fallbacks, and can resolve output_capabilities.image from model metadata.
• Image-output guard: Google gateway, direct Gemini and Vertex paths reject incompatible custom tools and structured output before dispatch when an image-output request is selected.
• Hook determinism: pre_tool_use, before_llm_call and tool_response_transform rewrite-capable hooks now run as sequential pipelines instead of concurrent first-rewrite-wins execution; the new add_context builtin can inject Go-template context without an external hook process.
• Safety and stability: the release expands safe/destructive shell patterns and fixes several transport/runtime issues, including Gemini keepalive SSE frames reaching the SDK parser and nondeterministic SQLite-store closing on Windows.

The immediately preceding v1.136.0 moved encrypted agent configuration from a request header into the request body/config-load envelope to avoid header-size limits. That historical transport change remains valid but is no longer the latest release boundary.

Post-release current-main: generated-media deltas

Checked upstream main at 56473dca0ab1fdc71351d6b39f4b4b420f5844cf includes merged PR #4023, one commit beyond v1.137.0. It introduces provider-agnostic MediaDelta values into runtime stream results and collects complete provider-generated inline media bytes, including media-only and terminal chunks. The initial implementation includes Gemini inline generated media and tests at the runtime/provider boundary.

The upstream PR is explicit about the limit of this evidence: this merge is not progressive partial-image presentation, remote binary streaming, persistence or TUI delivery. Those are deferred dependent changes. Therefore this page records #4023 as unreleased current-main runtime behavior rather than silently attributing it to stable v1.137.0.

Evidence boundaries

• Observed Docker Agent stable: v1.137.0, published 9 Sep 2026 at 14:24:40 UTC, tag target cfcca04b03ee829e9fd383bcc1e60fda65178ec1.
• Checked upstream main: 56473dca0ab1fdc71351d6b39f4b4b420f5844cf; PR #4023 generated-media delta support is unreleased relative to v1.137.0.
• Native coding harnesses: Claude Code, Codex, OpenCode and Pi in stable v1.137.0 documentation.
• Native MCP: server mode plus MCP tool consumption is established by Docker Agent primary documentation.
• Native A2A: server and remote-agent tool surfaces are established; stable docs label support early and list limitations.
• Native ACP: stdio server mode is established by stable documentation.
• Native UHP: not established.
• HarnessRouter backend support: not present in v0.15.7’s released ten-backend set.
• UHP conformance evidence: none attributed to Docker Agent.

Related pages

Read harness composition for subagent/runtime topology, UHP vs MCP for tool interoperability, UHP vs A2A for agent-to-agent boundaries, UHP vs ACP for host-to-agent integration, TrueForge for another complete agent runtime, and ecosystem for adoption classifications.

Primary sources

• Docker Agent repository
• Docker Agent v1.137.0
• Docker Agent v1.137.0 tag target cfcca04b
• Docker Agent README at v1.137.0
• Coding Harnesses at v1.137.0
• MCP Mode at v1.137.0
• A2A at v1.137.0
• ACP at v1.137.0
• PR #4023 — generated-media runtime deltas
• Docker Agent checked main 56473dca
• HarnessRouter v0.15.7