compose-for-agents: Ready-to-Run Docker Compose Demos for AI Agent Frameworks

What compose-for-agents Provides and Who It Is For

Composing a working AI agent system requires coordinating several moving parts: a language model (local or remote), one or more tool servers (often Model Context Protocol servers), an agent runtime (LangGraph, CrewAI, ADK, or another), and whatever application logic wraps it. Setting each of these up from scratch for an evaluation or proof-of-concept takes significant time.

compose-for-agents solves this by providing a set of self-contained Docker Compose projects, each of which wires together a specific agent framework with specific models and MCP tools. The README describes each demo as self-contained and configured using two steps: change directory into the demo folder, optionally create a .mcp.env file from the included example, and run docker compose up --build.

The audience is developers who want a working reference for how to run a specific agent framework with Docker, and who want to see how models, tools, and agent runtimes connect at the Compose service level. The repository is maintained by Docker, which means the examples are written to demonstrate Docker's own tooling: Docker Model Runner for serving models locally, and Docker Offload for cloud GPU execution when local hardware is not available.

Prerequisites: Docker Desktop and GPU Requirements

The README lists specific prerequisites. Docker Desktop version 4.43.0 or later, or Docker Engine, is required. A laptop or workstation with a GPU is listed as needed for running open models locally, with a MacBook given as an example. Teams without a GPU can use Docker Offload as an alternative to local model serving.

For Docker Engine on Linux, Docker Compose 2.38.1 or later is required, and GPU support must be enabled with the appropriate drivers installed. For Docker Desktop on Windows, the same GPU support requirements apply.

The README notes that demos which use models locally rely on Docker Model Runner, a Docker-integrated model serving layer. Demos that use external APIs (such as the Cerebras-hosted model in the ADK and Cerebras demo, or any demo using OpenAI models via the compose.openai.yaml override) do not require local GPU resources.

Running a Demo: The Standard Two-Step Process

Every demo in the repository follows the same pattern:

cd ./langgraph
docker compose up --build

If the demo requires MCP server credentials, a mcp.env.example file is included. You copy it and fill in your API tokens:

cp mcp.env.example .mcp.env
# edit .mcp.env with your tokens
docker compose up --build

The --build flag ensures that the local service images are built before starting. After the services are up, the demo is accessible according to its own documentation: some demos expose a chat UI in the browser, others are headless agents that run a task and print output.

Each demo directory is independent. You do not need to run any top-level setup before entering a specific demo directory. The docker compose up command starts only the services defined in that demo's compose.yaml file.

Switching to OpenAI Models Instead of Local Inference

Demos that support OpenAI models provide a compose.openai.yaml override file. To use it, first create a file named secret.openai-api-key in the demo directory containing your key:

sk-...

Then start the project with both Compose files:

docker compose -f compose.yaml -f compose.openai.yaml up

The override file reconfigures the model-serving service to call the OpenAI API instead of Docker Model Runner. This is useful in environments where a GPU is not available and Docker Offload is not set up.

Not all demos support this override. The README table indicates which demos use locally served models and which use remote models or mixed configurations.

The Demo Catalog and Agent Frameworks Covered

The README table lists 12 demos at the time of the last documented update, with a thirteenth directory (akka/) present in the top-level layout. The demos cover a range of agent frameworks and patterns:

Single-agent demos include a LangGraph SQL Agent that queries a PostgreSQL database using a qwen3 model, a Spring AI demo using Brave Search, and a Langchaingo demo using DuckDuckGo and gemma3.

Multi-agent demos include a CrewAI Marketing Strategy Agent using qwen3, an A2A (Agent-to-Agent) Multi-Agent Fact Checker using OpenAI, and an ADK Sock Store Agent with MongoDB and Brave integrations. The Agno demo summarises GitHub issues using qwen3 and the GitHub MCP server.

The Embabel Travel Agent is the most complex example listed, combining qwen3, Claude 3.7, llama3.2, an embedding model, and five MCP servers: brave, github-official, wikipedia-mcp, weather, google-maps, and airbnb.

The MinionS demo implements a local-remote collaboration protocol where a local qwen3 model handles lightweight tasks while gpt-4o handles tasks that require stronger reasoning, with cost routing between them.

The ADK and Cerebras demo uses a locally served qwen3 model for one agent and a Cerebras-hosted llama-4-scout model for another, demonstrating mixed local and remote inference within a single Compose deployment.

Limitations, Maintenance, and License

Each demo is illustrative rather than production-ready. The compose.yaml files in the demos do not include health checks, restart policies, secret management beyond environment files, or persistent volume configuration for stateful services like databases. Teams adapting a demo for production will need to add those elements.

The repository is dual-licensed under Apache-2.0 and MIT. The README states that you may choose either license to govern your use of Docker's contributions. Each individual demo directory may contain its own LICENSE file reflecting third-party licensing requirements from the frameworks or tools used in that demo.

The demos do not include comprehensive error handling or fallback behaviour for cases where the model fails to respond or an MCP server is unavailable. They are intended as starting points for understanding the composition pattern, not as reference implementations for production reliability.

The last push to the repository was on 2026-09-02. The repository does not use GitHub Releases; all changes are tracked through commits. The README notes that Docker Compose 2.38.1 or later is required on Linux, and that this version requirement may not be met by older Linux distribution packages.

Editorial conclusion

compose-for-agents is useful for engineers who want a working starting point for running an AI agent framework with Docker Compose, particularly when they want to test local model inference without external API costs. It is not a production deployment template; the demos are illustrative examples rather than hardened service configurations. Before using a demo as a starting point, check whether it requires a GPU for local inference or whether Docker Offload is available in your environment, and verify the Docker Desktop version requirement of 4.43.0 or later.

Frequently asked questions

Official sources

1. docker/compose-for-agents on GitHub
2. Issues
3. License: Apache-2.0
4. README