docker/docker-agent

If you already have API keys or a local model runner and want agent workflows you can version and share rather than script from scratch, Docker Agent is worth a look. It is a CLI plugin that reads a YAML agent definition and runs it, with OCI packages for distributing configs.

The problem

You want an assistant that can search the web, read local context and hand sub-tasks to specialist helpers, and you want the setup to be reviewable in a repo. Building that usually means writing glue code: provider client, tool wiring, delegation logic, prompt plumbing. With Docker Agent the loop is pasted into a YAML file with a model reference, instructions and toolsets, and docker agent run agent.yaml executes it; multi-agent teams and delegation are expressed in the same config. The result is a versionable artifact instead of an application.

What's different

The declarative config is the product: agents, models, toolsets and multi-agent relationships live in YAML, with a configuration reference and multi-agent concepts documenting the schema. Toolsets cover built-ins plus any MCP server, local, remote or containerized, which lets you reuse the growing MCP ecosystem rather than write adapters. Models are pluggable across OpenAI, Anthropic, Gemini, Bedrock, Mistral, xAI and Docker Model Runner, so the same config can point at a cloud key or a local model. RAG retrieval (BM25, embeddings, hybrid search, reranking) is available as a pluggable tool, and configs can be pushed to or pulled from an OCI registry.

The trade-off is that expressiveness is bounded by the YAML schema. When an agent needs behavior the config does not model, the documented escape hatch is the Go SDK, used to build something custom; HN commenter aheritier noted exactly that split, saying many cases need only iterating on YAML, while the Go API covers custom builds (comment). Debugging agent behavior therefore means reading traces and prompts rather than stepping through your own code, and sharing a config also means sharing its model and tool dependencies.

Who should try it

Good fit: a team that wants a repeatable internal assistant, such as a repository-aware go developer agent (the project uses one on itself), or a support/research agent chaining MCP tools, and wants it distributed as an OCI image. Poor fit: someone whose agent logic is mostly custom orchestration in code, who will hit the YAML ceiling and end up in the Go SDK anyway; or a user who only wants a chat client with no config to maintain. HN reactions split between those seeing another agent harness among many and those wanting to keep configuration as the unit of sharing (discussion).

Requirements and limitations

You need a model source: an API key for a hosted provider or a local model via Docker Model Runner, documented in the model setup walkthrough. Installation has several paths: Docker Desktop 4.63+ preinstalls the CLI plugin, Homebrew and binary releases also exist, with symlinking needed for the docker agent form; see installation. That means Docker is convenient but not strictly mandatory if you run the binary directly.

Ongoing upkeep is config and dependency work: model names, provider endpoints and MCP server references change, and packaged agents must be re-pulled. Anonymous telemetry is collected by default and documented under telemetry, so check that before internal rollout.

HotRepo's take

HotRepo's first recorded snapshot shows +1,271 stars on the monthly Go board, rank #22, dated 2026-10-26; a single sampled month cannot establish whether interest is rising or fading. The project was created 2025-09-01, so it is young. Before adopting, verify the YAML schema covers the delegation and tool permissions you need, and read the model setup page for the local path, since that changes whether a cloud key is required.