Skip to content
ChatGPT & LLMs

Deploy Enterprise AI Agents: Docker Agent v1.150.0

Install Docker Agent v1.150.0 and deploy enterprise AI agents with copy-paste commands, agent.yaml, doctor checks, and real install fixes.

6 min readIntermediate

The #1 failure mode for enterprise AI agents isn’t the wrong model. It’s six weeks of architecture decks and zero binaries on a laptop. Skip the phased playbook. You want a runtime that packages agents the way Docker packages containers: YAML in, process up, optional push to a registry.

Docker Agent v1.150.0 (released October 9, 2026 per GitHub Releases; Homebrew stable 1.150.0) is Docker Engineering’s CLI for that job. Invoke it as docker agent when installed as a plugin. Below: install pins, minimum config, doctor, and the breakage people actually hit.

What you actually need before install

The CLI is a Go binary. Pain lives on the model side.

Per Docker’s installation prerequisites (as of the v1.150.0 docs set): you need model access through a provider API key or Docker Model Runner (DMR). Docker Desktop is optional – pull it in when you want the pre-installed plugin, MCP tool containers, or DMR. Building from source wants Go 1.27+. No GPU for the agent process itself; GPU only if you host local weights.

OS coverage is macOS, Linux, and Windows. Headless/API hosts are usually Linux. Outbound HTTPS to your LLM provider is mandatory; add registry access if you pull OCI-packaged agents.

Official download source

One installer family on PATH. Mixing brew + a random GitHub binary is how you debug the wrong build at 2 a.m.

  • Docker Desktop 4.63+ – plugin already there; docker agent version
  • Homebrew – brew install docker-agent (formula stable 1.150.0 as of this writing)
  • Winget – winget install Docker.Agent
  • GitHub Releases – platform binaries
  • Docs – docs.docker.com/ai/docker-agent

Desktop 4.49-4.62 shipped the same line under the old name cagent. If a wiki still says cagent, it’s this project.

Install Docker Agent v1.150.0

Option A – Docker Desktop 4.63+

docker agent version
# Expect v1.150.0 or the Desktop-bundled build

Unknown command? Upgrade Desktop, or use brew/binary.

Option B – Homebrew

brew install docker-agent
docker-agent version

mkdir -p ~/.docker/cli-plugins
ln -sf "$(which docker-agent)" ~/.docker/cli-plugins/docker-agent
docker agent version

Option C – GitHub binary

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64;; aarch64) ARCH=arm64;; esac
curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-${OS}-${ARCH}" -o docker-agent
chmod +x docker-agent
sudo mv docker-agent /usr/local/bin/
docker-agent version

Windows: grab docker-agent-windows-amd64.exe, rename to docker-agent.exe, place on PATH or under %USERPROFILE%.dockercli-plugins.

The catch:DOCKER_AGENT_AUTO_UPDATE=1 only self-updates standalone GitHub binaries (SHA-256 verified; failed update keeps the current binary). Brew and Desktop ignore that env var – use brew upgrade / Desktop update instead.

Minimum viable agent.yaml

Keys never belong in YAML. Official secrets docs resolve them from env vars, --env-from-file, Docker Desktop secrets, a credential helper, or – still – ~/.config/cagent/.env. That directory name is historical. Teams grepping only for docker-agent miss env files and half of what doctor reports.

# Interactive store
docker agent setup

# Or shell-only
export OPENAI_API_KEY="sk-..."
# export ANTHROPIC_API_KEY="sk-ant-..."
# export GOOGLE_API_KEY="AI..."
agents:
 root:
 model: openai/gpt-4o
 description: Internal ops assistant
 instruction: |
 Help staff with internal runbooks only.
 Never invent credentials. Prefer tools over guesses.
 Production write access? Stop and ask.
 toolsets:
 - type: datetime
 - type: calculator
 - type: random

Those toolsets shipped in v1.150.0 (release notes also list DaoXE provider support and OSC 7501 status). Local weights path: pull a model with Docker Model Runner, then pass a dmr/... model id on docker agent run.

Verify before you demo

docker agent version
docker agent doctor
docker agent run
# docker agent run ./agent.yaml

doctor checks credentials, DMR reachability, and what auto model selection would pick. Non-zero exit = a real run would fail. Fix that before stakeholders watch.

First clean TUI reply changes the meeting. Everything before it was slides.

Install and startup errors

RequiredEnvError / no usable model. Zero cloud keys and no pulled DMR model. docker agent setup, export a key, or pull a DMR model and pass --model. Troubleshooting docs pair this with doctor as preflight.

context_length_exceeded. Shrink history, tighten instructions, or switch to a larger-context model.

Max iterations. The loop thrashed tools. Raise the iteration cap or run with debug and read the tool trace.

YAML parse errors. Tabs and bare : values. Spaces only.

DMR model not pulled. Error names the tag – pull it before run.

MCP / ref: docker:* tools. Desktop usually isn’t running. Start it, retry the toolset.

Upgrade, downgrade trap, uninstall

  • Desktop → update Docker Desktop (plugin rides along)
  • Brew → brew upgrade docker-agent
  • Winget → winget upgrade Docker.Agent
  • Standalone binary → re-download from Releases (or the auto-update env var above)

v1.150.0 fixed budget enforcement on API-server native runtimes and agent limits that silently dropped on A2A session resume. If you expose agents over the API, take the upgrade.

Downgrade: session DB migrations move forward. Older binaries can refuse a newer DB (“newer-database” style error in official troubleshooting). Snapshot the DB before you roll back.

brew uninstall docker-agent
winget uninstall Docker.Agent
rm -f /usr/local/bin/docker-agent ~/.docker/cli-plugins/docker-agent
# optional secrets wipe - note the historical path:
rm -rf ~/.config/cagent

Desktop-bundled plugin leaves with Desktop. No separate uninstall package.

FAQ

Do I need Kubernetes on day one?

No. CLI on a laptop or one VM is enough to prove the agent. Orchestrators come after the YAML works.

Where did docker agent setup put my key?

Picture this: you search ~/.config/docker-agent, find nothing, assume setup failed. Check ~/.config/cagent/.env (owner-only perms) or the platform keychain. docker agent doctor prints a SOURCE column – environment vs env-file vs keychain – so you stop guessing.

How do I hand the same agent to another team?

Ship the YAML (plus referenced assets) as an OCI artifact the same way you push an image, then docker agent run myorg/agent:tag on their side. Definition is shared; credentials are not. Each environment keeps its own keys in env / Desktop secrets / that cagent env file. If their doctor is red and yours is green, it’s almost always provider keys or a missing DMR pull – not the YAML.

Run docker agent doctor. Fix what it flags. Then docker agent run with one paragraph of instruction tied to a real internal workflow – not a generic chatbot persona.

Related AI Tools