Docker Agent es el runner open source de Docker para agentes de IA que describís en un archivo YAML en vez de código. La documentación lo presenta como “lo que docker run es para los contenedores, pero para agentes”: declarás un modelo, instrucciones y herramientas, y lo lanzás desde la terminal como plugin de Docker CLI. El repo ronda las 4.5k estrellas bajo Apache-2.0 y publicó cinco releases entre el 28 de septiembre y el 9 de octubre de 2026.
El loop central en una línea: docker agent run agent.yaml. Esta guía sale del README y la documentación al 2026-10-14. Los leí; no ejecuté la herramienta para este artículo, así que cada comando está documentado, no medido.
1. ¿Qué es Docker Agent?
Docker Agent construye y ejecuta agentes de IA a partir de una configuración declarativa. Se distribuye como plugin de Docker CLI (docker agent), acepta YAML o HCL, y la documentación aclara lo que no es: no es un framework de código, no es un SaaS alojado, no es un modelo. Habla con muchos proveedores (Anthropic, OpenAI, Google, Mistral, OpenRouter y modelos locales vía Docker Model Runner, entre otros), conecta herramientas incluyendo cualquier servidor MCP y empaqueta los agentes como artefactos OCI que podés subir a un registry.
~4.5k
Estrellas
Repo en GitHub, 14 oct 2026
Apache-2.0
Licencia
Open source
v1.150.0
Última release
9 oct 2026
Go
Stack
Plugin de Docker CLI
Leído de la página del repo y del feed de releases el 2026-10-14 (la API REST estaba limitada por rate limit desde mi red). El repo muestra 521 forks; la página de v1.150.0 lista tres contribuyentes. Las estrellas cambian a diario.
Una aclaración de nombres, porque los resultados de búsqueda mezclan ambos: el proyecto se llamaba cagent. La documentación de Docker dice que Docker Desktop 4.49 a 4.62 lo traía con ese nombre, y que 4.63 y posteriores lo incluyen como Docker Agent. Quedan rastros: la configuración de usuario vive en ~/.config/cagent/ y las variables CAGENT_* anteriores se siguen aceptando como alias.
La documentación sigue a main
Los docs en GitHub Pages dicen que siguen la rama main y pueden describir funciones todavía no publicadas; las páginas estables están en docs.docker.com/ai/docker-agent. Si una propiedad de la referencia no funciona en tu versión, revisá las notas de release antes de depurar tu YAML.
2. Cómo Funciona: Cuatro Pasos del YAML al Agente en Ejecución
El modelo mental entra en cuatro pasos. Todo sale de las páginas de configuración, herramientas y multi-agente de la documentación.
1. Definilo en un archivo
Una config necesita al menos un agente y puede sumar models, rag, mcps, providers, permissions, commands, skills y toolsets reutilizables, más metadata para distribución. Existe una clave version de nivel superior (los docs listan el esquema 16 como actual y dicen que los archivos viejos se migran solos). Los secretos quedan fuera del archivo: referencialos como ${env.NOMBRE}.
2. Corré el loop, con límites
docker agent run abre una UI en terminal, --exec ejecuta tareas puntuales y serve api expone HTTP. El loop llama al modelo, pasa cada tool call por una compuerta de permisos y repite. Defaults que conviene conocer: max_iterations es 0 (ilimitado), max_consecutive_tool_calls es 5 y la compactación de sesión se dispara al 0.9 de la ventana de contexto.
3. Equipalo con toolsets
Los built-in cubren filesystem, shell, think, todo, memory, fetch, RAG y más. MCP viene en tres sabores: ref: docker:<nombre> corre un servidor del catálogo en un contenedor vía el MCP Gateway, command/args lanza un proceso stdio local y remote.url conecta a un servidor streamable HTTP o SSE.
4. Componé y distribuí
sub_agents delega con una llamada a transfer_task; handoffs le pasa la sesión completa a un par. docker agent share push publica el YAML en cualquier registry OCI, y serve mcp o serve api convierte el mismo archivo en herramientas MCP o endpoints HTTP.
3. El YAML, Propiedad por Propiedad
Estas son las propiedades de agente que usaría primero, con los defaults que declara la página de referencia.
modelUn string provider/model como openai/gpt-5-mini, o la clave de una entrada con nombre bajo models:. Obligatorio salvo que uses harness.
descriptionUna línea sobre el rol. El coordinador la usa para elegir a quién delegar, así que escribila como documentación de API.
instructionEl prompt de sistema, inline o desde instruction_file (solo rutas relativas, sin rutas absolutas ni ..).
toolsetsLista de herramientas, cada una con un type: filesystem, shell, think, mcp y más. use_toolsets mezcla grupos con nombre definidos arriba.
sub_agents / handoffsNombres locales o referencias OCI. sub_agents habilita transfer_task; handoffs habilita el cambio entre pares en la misma sesión.
max_iterationsLimita el loop de tool calls. 0 es ilimitado; los docs consideran típico entre 20 y 50 para agentes de desarrollo.
fallbackModelos de respaldo probados en orden: retries (default 2) ante errores 5xx y un cooldown (default 1m) tras un 429.
hooksHooks de ciclo de vida como pre_tool_use, tool_guard y session_end, junto a structured_output para respuestas con esquema.
Un equipo de dos agentes (el ejemplo debugger de los docs, sin comentarios)
agents:
root:
model: openai/gpt-5-mini
description: Bug investigator
instruction: |
Examine error output, stack traces, and source to determine the root cause of a bug.
Describe the problem and its cause clearly.
Hand the implementation of any fix to the fixer agent.
sub_agents: [fixer]
toolsets:
- type: filesystem
- type: mcp
ref: docker:duckduckgo
fixer:
model: anthropic/claude-sonnet-4-5
description: Fix implementer
instruction: |
Produce fixes for bugs the investigator has diagnosed.
Keep changes small and focused, and add tests that guard against regressions.
toolsets:
- type: filesystem
- type: shellLos strings de modelo son ejemplos de la documentación, no recomendaciones. Poné los modelos que tus cuentas puedan usar hoy; un modelo con nombre bajo models: te deja definir provider, max_tokens y thinking_budget una sola vez y referenciarlo por clave.
Toolsets MCP: los tres sabores (ejemplos separados de los docs, combinados)
toolsets:
# 1. Docker MCP catalog, run in a container through the gateway
- type: mcp
ref: docker:github-official
tools: ["list_issues", "create_issue"]
# 2. Local stdio server
- type: mcp
command: python
args: ["-m", "mcp_server"]
env:
API_KEY: ${env.MY_API_KEY}
# 3. Remote server with a bearer token
- type: mcp
remote:
url: "https://mcp.linear.app/mcp"
transport_type: "streamable"
headers:
Authorization: "Bearer ${env.LINEAR_TOKEN}"Advertencias de delegación según los docs
- • transfer_task es secuencial: el padre espera al hijo, y los docs lo describen como siempre auto-aprobado. Para trabajo en paralelo usá el toolset background_agents.
- • handoffs depende del modelo. El modelo puede omitir la llamada a handoff, así que usá force_handoff cuando el pipeline deba ser estricto (sin autorreferencia ni ciclos).
- • Los sub-agentes externos por tag se re-resuelven en cada ejecución. Fijá un digest @sha256: para evitar arranques lentos o trabados.
4. Quickstart: Verificado Contra el README el 2026-10-14
Cada comando sale del README o de la página de docs que indica su etiqueta. Los listo, no corro instaladores por vos: leé qué hace un paquete antes de instalarlo.
Instalación (README; winget de docs.docker.com)
# Docker Desktop 4.63+ bundles the plugin docker agent version # Homebrew (macOS / Linux) brew install docker-agent docker-agent version # Windows (docs.docker.com) winget install Docker.Agent
Seteá la key del proveedor y corré tu YAML (README)
export OPENAI_API_KEY=sk-... docker agent run agent.yaml
Otras formas de correrlo (home de docs y quickstart)
docker agent run docker agent run myorg/agent:tag docker agent new docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app" cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?"
Modelo local, sin API key (página Set Up a Model)
docker model pull ai/qwen3 docker agent doctor docker agent run --model dmr/ai/qwen3
docker agent vs docker-agent
Homebrew instala un binario docker-agent. Para invocarlo como docker agent, el README indica crear un symlink en ~/.docker/cli-plugins/docker-agent, o podés ejecutar docker-agent directamente. Docker Desktop 4.63+ ya incluye el plugin. El README también lista ANTHROPIC_API_KEY y GOOGLE_API_KEY como alternativas a OPENAI_API_KEY.
5. Guardrails: Modos de Seguridad, Sandbox, Secretos y Telemetría
Un agente con toolsets de filesystem y shell puede modificar tu máquina. Los docs te dan cuatro modos de seguridad y un sandbox; leelos antes de la primera ejecución.
strict
Pregunta antes de cada llamada.
balanced
Ejecuta las llamadas que el runtime marca como seguras y pregunta por el resto.
restricted
Ejecuta las seguras y deniega el resto sin preguntar. Pensado para corridas desatendidas.
autonomous
Ejecuta todo. Es el comportamiento legado de --yolo; las reglas deny y los hooks de guard siguen aplicando.
Boceto de guardrails armado con ejemplos sueltos de los docs (no es un archivo que corrí)
agents:
root:
model: anthropic/claude-sonnet-4-5
instruction: You are a careful repo assistant.
max_iterations: 30
toolsets:
- type: filesystem
- type: shell
permissions:
allow:
- "read_*"
- "shell:cmd=ls*"
ask:
- "shell:cmd=git push*"
deny:
- "shell:cmd=sudo*"
runtime:
safety: balancedLos permisos no son un límite de seguridad
La página de permisos aclara que se aplican del lado del cliente y ayudan a evitar accidentes. Para aislamiento apunta a --sandbox, que corre el agente en una VM sandbox de Docker, monta solo el directorio de trabajo en lectura-escritura y deniega el egreso por defecto. Además: un YAML de terceros puede declarar runtime.safety: autonomous, y entonces ejecuta cada llamada sin preguntar. Leé las configs antes de correrlas.
La telemetría viene activada por defecto
La página de telemetría lista nombres de comandos y argumentos, nombres de agentes y tipos de modelo, nombres de herramientas con éxito o fallo, conteo de tokens con costo estimado y metadata de sesión. Advierte que argumentos y texto de errores pueden incluir prompts, rutas de archivos o secretos. Desactivala con la variable de abajo, antes de comandos que toquen datos sensibles.
Desactivar telemetría y correr dentro de un sandbox (docs)
TELEMETRY_ENABLED=false docker agent run agent.yaml docker agent run --sandbox agent.yaml
Los binarios MCP pueden autoinstalarse
Si un comando MCP no está en tu PATH, la página de MCP dice que Docker Agent lo busca en el registry de aqua y lo instala. Se desactiva por toolset con version: "false" o globalmente con DOCKER_AGENT_AUTO_INSTALL=false. Los secretos se resuelven desde variables de entorno, secretos de Compose, ~/.config/cagent/.env y algunas fuentes más, y redact_secrets viene activado; los docs llaman a la redacción defensa en profundidad, no una garantía.
6. Casos de Uso Donde Encaja
Cuatro lugares donde un runner YAML-first se gana su lugar.
Agentes de equipo como artefactos compartibles
Revisá un YAML en un pull request, subilo a tu registry y que tus compañeros corran docker agent run myorg/agent:tag. Es el flujo de imágenes que ya conocés, incluido el pinning por digest.
Automatización puntual en scripts
--exec más un pipe convierte al agente en una herramienta Unix: pasale un log o un diff y leé la respuesta en stdout. El ejemplo de los docs le pasa un log de errores por pipe.
Agentes como herramientas dentro de Claude Code o Claude Desktop
serve mcp expone cada agente de una config como una herramienta MCP separada. El transporte HTTP usa por defecto una política de seguridad restricted y exige --auth-token en direcciones que no sean loopback.
Evaluá antes de confiar
docker agent eval reproduce sesiones grabadas y puntúa tool calls, relevancia y aserciones, con --repeat para pass@k y --baseline para fallar el CI ante regresiones. Necesita un runtime de contenedores.
Distribuir, exponer, evaluar (comandos de los docs)
docker agent share push ./debugger.yaml myusername/debugger docker agent share pull myusername/debugger docker agent serve mcp ./agent.yaml docker agent serve api agent.yaml --listen 127.0.0.1:8080 docker agent eval agent.yaml
Ojo con serve api: poné --auth-token si escucha fuera de loopback, y --session-workingdir-root en setups multiusuario. Un docker agent run --listen adjunto no tiene autenticación integrada, según los docs.
7. Cuándo NO Usar Docker Agent
Un runner YAML encaja en una franja angosta de problemas. Estas son las situaciones donde miraría otra opción, o al menos iría más despacio.
Una superficie que cambia rápido
Cinco tags en doce días (v1.146.0 el 28 de sep a v1.150.0 el 9 de oct), docs que siguen a main y un renombrado reciente desde cagent. Fijá tu versión y leé las notas de release en cada upgrade.
La telemetría es opt-out
Está bien en una laptop personal; es una conversación de políticas en entornos regulados, porque los argumentos pueden llevar texto sensible y tenés que imponer TELEMETRY_ENABLED=false vos mismo.
Una comunidad chica
Unas 4.5k estrellas y tres contribuyentes listados en la última release, con soporte canalizado a un canal de Slack de la comunidad de Docker. Esperá menos guías de terceros y menos recetas probadas en batalla.
El YAML tiene un techo
Lógica de negocio con ramas, estado propio, código de herramientas tipado y tests unitarios sobre tus funciones llevan un archivo declarativo más allá de lo que hace bien. Ahí un framework code-first rinde más.
✅ Usalo si...
- • Ya vivís en Docker: Desktop, Compose, registries
- • Querés agentes como archivos revisables en git, no módulos
- • Querés un equipo planificador más programador sin código pegamento
- • Un solo artefacto debe correr en terminal, tras HTTP o como herramienta MCP
- • Tus agentes son sobre todo loops de tool calls sobre archivos, shell y servidores MCP
⚠️ Considerá un framework code-first si...
- • Necesitás control de flujo propio, estado durable o checkpoints humanos escritos como código
- • Tu equipo testea agentes con interfaces tipadas y tests unitarios en un solo lenguaje
- • Entregás un producto con SLA y necesitás una API madura y estable
- • Tu política prohíbe telemetría opt-out y no podés imponer la variable
- • Necesitás un runtime alojado multi-tenant: esto es una CLI y un servidor que corrés vos
Regla de oro
Tratá el YAML de un agente de terceros como un script de shell: leelo antes de correrlo. El prompt, los toolsets, los comandos MCP y los defaults de seguridad viven en ese único archivo.
Conclusión
Docker Agent hace una apuesta clara: un agente es un artefacto de configuración, versionado en git, compartido por un registry y ejecutado por un runtime chico. Si tu equipo ya piensa en imágenes y archivos Compose, la apuesta es fácil de adoptar, y los guardrails que describen los docs (modos de seguridad, sandbox, redacción de secretos activa por defecto) hacen las preguntas correctas.
Empezá chico: un agente, toolset de filesystem con readonly: true, modo balanced, telemetría apagada. Sumá un sub-agente recién cuando el agente solo se porte bien, y agregá evals antes de que alguien dependa de él. Si necesitás agentes así integrados en un stack real y con guardrails, es el tipo de hueco que cierro en trabajos de rescate de proyectos.
