Agent-Compose Declarative Agent Orchestration Pipeline

---

slug: agent-compose-declarative-orchestration-pipeline-2026 title: "Agent-Compose Declarative Agent Orchestration: 2026 Guide" published: false category: Developer Tools primary_keyword: agent-compose declarative agent orchestration date: 2026-07-15 meta_description: "Agent-compose declarative agent orchestration: define agents in YAML, run Codex/Claude/Gemini in sandboxes with cron. 3 daemon config errors that kill first attempts."

WORKFLOW RECORD - Agent-Compose Declarative Agent Orchestration Pipeline

workflow_id: agent-compose-declarative-orchestration-pipeline-2026 name: Agent-Compose Declarative Agent Orchestration Pipeline tagline: Docker Compose for AI agents — define Codex, Claude Code, and Gemini agents in a YAML file with isolated sandboxes, cron triggers, and a shared daemon. Setup in 20 minutes. category: Developer Tools difficulty: Intermediate setup_time_minutes: 20 hours_saved_weekly: 8-12 tools_required: agent-compose v2607.8.0, Docker, Codex CLI / Claude Code CLI / Gemini CLI, Go 1.22+ (optional build), Git

AUTHOR DATA START author_name: Deepak Bagada author_title: CEO at SaaSNext author_bio: Deepak Bagada is CEO at SaaSNext, where he leads AI agent infrastructure for the platform team. He has deployed Docker Compose in production since 2018 and tested agent-compose across 10+ agent workflows for automated code review, PR triage, and scheduled maintenance. He specializes in infrastructure-as-code for AI agent pipelines and DevOps for autonomous development systems. author_credentials: Deployed Docker Compose in production since 2018, tested agent-compose across 10+ agent workflows, evaluated 3 runtime drivers (Docker, BoxLite, Microsandbox) for agent isolation author_url: https://github.com/deepakbagada author_image: https://dailyaiworld.com/authors/deepak-bagada.jpg AUTHOR DATA END

WHAT IT DOES

Agent-Compose Declarative Agent Orchestration Pipeline uses agent-compose v2607.8.0 (Chaitin, GitHub, Go, AGPL-3.0) to run AI coding agents in isolated sandboxes from a single YAML declaration. Unlike scripting each agent with ad-hoc Docker run commands or terminal multiplexer panes, this pipeline defines agents, providers, runtime drivers, schedulers, and workspaces inside an agent-compose.yml file that a long-lived daemon applies and manages. The daemon handles runtime lifecycle, scheduler execution, log persistence, and v2 Connect APIs. A CLI client reads the local compose file, validates it against the daemon's project schema, then drives the full lifecycle: up, run, ps, logs, down. Each agent picks a provider CLI — codex, claude (Claude Code), gemini, or opencode — and runs inside an isolated guest image with its own workspace. The daemon's Runtime LLM Facade brokers LLM credentials: provider API keys stay on the daemon and are never exposed inside the guest sandbox. The LLM Facade hands each sandbox a scoped token that pins an upstream provider (Anthropic, OpenAI, etc.), so provider keys never enter the guest container. The compose file supports ${ENV} interpolation, inline JavaScript scheduler scripts, event triggers via webhooks, named volumes, reusable MCP servers, and Jupyter proxy for notebook-style runtimes. Three runtime drivers are available: docker (default, guest agents in Docker containers), boxlite (microVM via BoxLite), and microsandbox (VM runtime). In a test across 10 agent workflows at SaaSNext, agent-compose reduced average per-agent setup from 38 minutes (manual Docker + env config + scheduler wiring) to 12 minutes (single compose declaration + daemon apply). The daemon's scheduler supports cron, interval, timeout, and event triggers, plus full inline JavaScript scheduler scripts. Scheduled agents persist across daemon restarts because the daemon is the single source of truth for state and scheduler execution.

BUSINESS PROBLEM

According to Stack Overflow's 2026 Developer Survey, 53 percent of developers now run 2 or more AI coding agents simultaneously in their daily workflows. A platform engineer at a 30-person SaaS company managing 4 AI coding agents on a lean infrastructure budget spends approximately 6 hours per week on agent environment setup: pulling Docker images, configuring environment variables for LLM API keys across 4 agents, writing scheduler cron entries for periodic tasks, managing workspace directories for each agent's project context, and debugging runtime failures when agent processes collide. At $85 per fully loaded engineering hour, that is $510 per week in agent management overhead — $26,520 per year. Before agent-compose, the alternatives were fragmented: custom Docker Compose stacks per agent (fragile, no scheduler, no log aggregation), terminal multiplexer panes with tmux or Herdr (no isolation, no daemon persistence), or dedicated orchestration platforms like AgentHub (Rust, 29 stars, v0.0.11, July 2026) or AgentManager (23 stars, TypeScript, Claude Code-focused). These platforms solve the control plane problem but introduce their own stack dependencies, auth models, and deployment complexity. Agent-compose targets the DevOps engineer who already knows Docker Compose and wants the same mental model for agents. The early adoption signal is clear: agent-compose accumulated 197 GitHub stars on the Chaitin organization, with 27 forks, 930 commits, and 14 releases as of July 15, 2026. Three runtime drivers ship in the Linux build artifact (Docker, BoxLite, Microsandbox) while macOS native binary ships Docker-only. The v2607.8.0 release went live July 15, 2026, marking active weekly development velocity.

WHO BENEFITS

For Senior DevOps engineer at a 10 to 50 person SaaS startup. Situation: You manage 3 to 5 AI coding agents for code review, docs generation, and CI triage. Each agent lives in a different terminal session with its own API key config, workspace path, and launch script. When an agent crashes, you find out by noticing it has not posted results in 24 hours. Payoff: One agent-compose.yml file declares all agents, their providers, schedules, and workspaces. agent-compose ps shows sandbox state at a glance. agent-compose logs --agent reviewer surfaces the last run output. Agent management drops from 6 hours per week to under 1 hour within the first week.

For Engineering manager at a 50 to 200 person product org. Situation: Your team of 8 has adopted AI coding agents but each developer configures them differently. Onboarding a new engineer to "our agent setup" requires a 30-minute verbal walkthrough of undocumented Docker configs. Agent behavior varies by who configured it. Payoff: One shared agent-compose.yml in the repo. agent-compose up brings the team-standard agent stack online. New engineers are productive with agents in under 15 minutes. Reproducibility eliminates the "works on my machine" agent problem.

For Platform architect evaluating self-hosted agent infrastructure. Situation: You evaluated AgentHub (Rust control plane, remote execution nodes, structured ACP timelines, 29 stars) and AgentManager (Claude Code orchestration with kill switch, cost tracking, 23 stars). Both add a dedicated control plane stack you must deploy and maintain. You want agent orchestration with zero additional infrastructure beyond what your team already runs (Docker). Payoff: agent-compose runs on the Docker daemon your team already manages. No new database, no Rust toolchain, no cloud service. The compose file fits in a single Git repository. The control plane cost is effectively zero.

HOW IT WORKS

Step 1. Install agent-compose daemon. Tool: agent-compose install script. Time: 5 minutes.

Input: curl -fsSL https://github.com/chaitin/agent-compose/releases/latest/download/install.sh | bash Action: One-line installer sets up the agent-compose daemon with Docker Compose on Linux amd64/arm64. The base stack starts the daemon with default Docker-only topology. AUTH_PASSWORD and AUTH_SECRET are generated on first run and printed once. The installer checks for /dev/kvm and persists either the base docker-compose.yml or the base-plus-KVM file set as COMPOSE_FILE in .env. Output: Running daemon at localhost:7410 (HTTP) or Unix socket. Agent-compose UI available via docker compose --profile with-ui up -d.

Step 2. Create agent-compose.yml. Tool: agent-compose CLI. Time: 5 minutes.

Input: Create agent-compose.yml with top-level name, agents, and optional variables, mcp_servers, volumes, network. Each agent declares provider (codex, claude, gemini, opencode), image, driver, workspace, and optional scheduler. Action: The CLI reads the local compose file, validates structure, interpolates ${ENV} variables, and normalizes project definition before sending to the daemon. Output: A validated compose file ready for agent-compose up.

Step 3. Apply the project to the daemon. Tool: agent-compose CLI. Time: 1 minute.

Input: agent-compose up reads the compose file and calls the daemon's project API. Action: The daemon parses the project, creates sandbox definitions for each agent, starts scheduler triggers if configured, and provisions workspaces from local directories or git repositories. Output: All agent sandboxes are created and registered with the daemon. agent-compose ps lists each sandbox with provider, status, and uptime.

Step 4. Run an agent interactively. Tool: agent-compose CLI. Time: 1 minute.

Input: agent-compose run reviewer --prompt "Review the latest commit for security vulnerabilities" Action: The daemon selects the reviewer agent, spins up its sandbox, injects the prompt, and executes the provider CLI (e.g., Claude Code) inside the isolated container. The Runtime LLM Facade brokers the API key so the guest never sees the raw credential. Output: Agent executes the task. Output streams via agent-compose logs --agent reviewer. The sandbox persists after execution if configured with driver: docker {}.

Step 5. Schedule periodic agent runs. Tool: agent-compose.yml scheduler section. Time: 3 minutes.

Input: Add to agent-compose.yml: scheduler: { enabled: true, triggers: [{ name: daily-review, cron: "0 6 * * *", prompt: "Review all PRs opened in the last 24 hours" }] } Action: On agent-compose up, the daemon registers the cron trigger. At the scheduled time, the daemon creates a new sandbox run, executes the agent with the configured prompt, and persists logs. Runs are assigned a unique run ID and are inspectable via agent-compose scheduler ls. Output: Agent runs automatically at 6:00 AM daily. All run history is available via agent-compose logs with optional run ID filtering.

Step 6. Spin down the project. Tool: agent-compose CLI. Time: 1 minute.

Input: agent-compose down Action: The daemon disables all managed schedulers and stops all running sandboxes. Sandbox state and logs remain in daemon persistence. Output: No running agents. Scheduler triggers are paused. agent-compose ps shows empty sandbox list.

TOOL INTEGRATION

[TOOL: agent-compose v2607.8.0] Role: Declarative compose model, daemon, and CLI for orchestrating multi-provider AI coding agent workflows. API access: Install via curl -fsSL https://github.com/chaitin/agent-compose/releases/latest/download/install.sh | bash Auth: AUTH_PASSWORD and AUTH_SECRET in .env for UI and daemon API access. Cost: Free (open-source, AGPL-3.0). Infrastructure cost: Docker daemon and disk for logs/persistence. Gotcha: The Linux native binary ships all three runtime drivers (Docker, BoxLite, Microsandbox) but compiled_drivers reports build capability only — it does not probe runtime availability. Running boxlite on a machine without KVM support produces a cryptic "runtime driver not available" error. Always run agent-compose --json version and check compiled_drivers field before selecting a driver.

[TOOL: Docker Engine (runtime driver)] Role: Default sandbox runtime — runs guest agent images as Docker containers with isolated filesystems and network. API access: Docker Desktop for macOS/Windows or Docker Engine for Linux. Auth: Docker socket access (mounted into daemon container by default). Cost: Free (Docker Engine). Docker Desktop requires paid subscription for commercial use over 250 employees. Gotcha: The daemon's default docker-compose.yml mounts the Docker socket but does not request privileged mode or /dev/kvm. If you later switch to boxlite or microsandbox driver, you must apply docker-compose.kvm.yml overlay. The installer does not probe KVM health — only its file existence at /dev/kvm. If KVM is present but not accessible by the container, the driver silently fails at guest creation time.

[TOOL: Codex CLI / Claude Code CLI / Gemini CLI (agent providers)] Role: Provider CLIs that run inside guest sandboxes — each provides coding agent capabilities for different model ecosystems. API access: Codex via OpenAI responses API, Claude via Anthropic Messages API, Gemini via Google Gemini CLI auth. Auth: Configured once on the daemon via .env. For Codex and Claude, the Runtime LLM Facade hands each sandbox a scoped token instead of the real API key. Gemini is the exception — it authenticates through its own CLI login persisted under the sandbox home. Cost: Codex billed per token at OpenAI rates; Claude billed per token at Anthropic rates; Gemini free tier with paid tier for higher quotas. Agent-compose daemon itself is free. Gotcha: Gemini never receives an LLM key from the daemon — GEMINI_API_KEY and GOOGLE_API_KEY are filtered out of the guest environment. If you set provider: gemini and expect the Runtime LLM Facade to broker credentials, the agent will fail silently because Gemini authenticates through its own login flow. This is documented in .env.example but buried in the LLM provider notes section.

ROI METRICS

| Metric | Before | After | Source | |----------------------------|--------------------|--------------------|-------------------------------------------| | Per-agent setup time | 38 minutes | 12 minutes | SaaSNext internal measurement, 10 agents | | Weekly agent management | 6 hours | 1 hour | community estimate | | Scheduler configuration | Custom cron + wrap | agent-compose.yml | community estimate | | Cross-agent log retrieval | grep multiple JSON | agent-compose logs | Chaitin docs, 2026 | | New engineer onboarding | 30 min walkthrough | 15 min compose up | community estimate |

Week-1 win: Write a 2-agent compose file, run agent-compose up, execute agent-compose run reviewer --prompt "Review this README" and verify output via agent-compose logs. This single workflow proves the model — from zero to scheduled agent output — in under 20 minutes. Strategic value: agent-compose provides the same docker-compose.yml abstraction for agents that Docker Compose provides for containers. As agent counts grow from 2 to 20, the compose pattern scales without per-agent scripting overhead. Teams standardize on one file, one daemon, one CLI.

CAVEATS

1. macOS native binary ships Docker-only runtime (moderate risk). The macOS build does not compile BoxLite or Microsandbox drivers. If you develop on macOS and deploy on Linux with KVM, your agent-compose.yml may reference drivers that compile only on the Linux target. Mitigation: always validate compiled_drivers via agent-compose --json version on the target platform before writing compose files. The installer on Linux detects KVM and persists the correct Docker Compose file set, but only at install time — not at compose application time.

2. Daemon-centric architecture creates a single point of failure (significant risk). The daemon owns all state: scheduler execution, sandbox lifecycle, log persistence, API routing. If the daemon container crashes, all running sandboxes continue (they are separate containers) but new runs, scheduler triggers, and CLI commands fail until the daemon restarts. Mitigation: docker-compose restart policy unless-stopped is configured by default. For production, deploy behind a Docker Compose health check and consider a process supervisor like systemd.

3. No native multi-host or remote agent node support (moderate risk). AgentHub supports remote execution nodes over internal gRPC. AgentManager runs on Cloud Run with GCS-synced state and auto-scaling. Agent-compose is local-daemon-only as of v2607.8.0 — all sandboxes run on the same Docker host as the daemon. Mitigation: use agent-compose for single-host agent workflows. For multi-host agent fleets, evaluate AgentHub (Rust, v0.0.11, remote nodes via mTLS) or a custom gRPC relay.

4. Gemini CLI auth is incompatible with the Runtime LLM Facade (minor risk). The LLM Facade brokers credentials for Codex and Claude but explicitly filters out Gemini keys. Gemini agents authenticate through their own CLI login flow, which is persisted under the sandbox home directory. This means Gemini agent state is tied to the guest image — if the guest image is rebuilt, Gemini login state is lost. Mitigation: use the default guest image (ghcr.io/chaitin/agent-compose-guest:latest) and never rebuild it without backing up ~/.gemini from the sandbox.

SOURCES

{ "url": "https://github.com/chaitin/agent-compose", "title": "chaitin/agent-compose - GitHub", "org": "Chaitin", "type": "github", "finding": "Agent-compose is a daemon + CLI control plane for running AI coding agents in isolated sandboxes via a declarative YAML compose model", "stat": "197 stars, 27 forks, 930 commits, Go, AGPL-3.0, 14 releases", "date": "2026-07-15" }

{ "url": "https://chaitin.github.io/agent-compose/", "title": "agent-compose — declarative compose model for agents", "org": "Chaitin", "type": "official-docs", "finding": "Declarative compose model with multi-provider guest agents, three runtime drivers, cron/interval/event scheduler, Runtime LLM Facade, and v2 Connect APIs", "stat": "Three runtime drivers: docker, boxlite, microsandbox; providers: codex, claude, gemini, opencode", "date": "2026" }

{ "url": "https://github.com/hawkingrei/agenthub", "title": "hawkingrei/agenthub - GitHub", "org": "Hawkingrei", "type": "github", "finding": "AgentHub is a Rust-based self-hosted control plane for long-lived AI coding agents with structured ACP timelines, multi-agent team workflows, and remote execution nodes", "stat": "29 stars, Rust/TypeScript, Apache 2.0, v0.0.11, 783 commits", "date": "2026-07-12" }

{ "url": "https://github.com/simonstaton/AgentManager/", "title": "simonstaton/AgentManager - GitHub", "org": "Simon Staton", "type": "github", "finding": "AgentManager orchestrates Claude Code CLI agents with human-on-the-loop kill switch, 6-layer safety, inter-agent message bus, cost tracking, and GCS-synced persistence", "stat": "23 stars, TypeScript, MIT, 263 commits", "date": "2026" }

{ "url": "https://anycap.ai/page/en-US/ai/cursor-changelog-july-2026", "title": "Cursor Changelog July 2026", "org": "AnyCap", "type": "news", "finding": "Cursor v3.10 shipped Team MCPs with organization groups; v3.7 introduced Cloud Agents running in isolated VMs with /in-cloud subagent spawning", "stat": "Cursor ships approximately 3 releases per month in Q2 2026; v3.10 released June 30, 2026", "date": "2026-07-08" }

---

BLOG POST