agent-compose：给 AI coding agent 造一个"Docker Compose"

痛点场景：当你需要同时跑多个 AI agent 时

假设你正在开发一个复杂的多智能体系统：需要 Claude Code 写代码、Codex 做代码审查、Gemini 处理文档生成。你会怎么做？

开三个终端窗口，每个分别配置 API key、设置 workspace、启动进程……然后发现 API key 全暴露在各个子进程的进程环境变量里，每次重启都要重新配置。更痛苦的是，当某个 agent 意外崩溃时，你可能根本不知道它留下了什么状态，要清理整个开发环境。

chaitin/agent-compose 正是为解决这类问题而生。它的核心思路非常直观：把 Docker Compose 的心智模型搬到 AI agent 领域——用声明式配置文件描述 agent，用一个常驻 daemon 管理 agent 的完整生命周期，API key 始终留存在 daemon 侧，不进入隔离的 guest 环境。

chaitin org avatar

项目背景：来自安全厂商的开源实验

agent-compose 由 长亭科技（Chaitin） 开源。这家公司以 Web 应用安全产品（如雷池 WAF）闻名，在安全研究领域积累深厚。2024 年起，长亭内部开始探索 AI coding agent 的工程化课题——如何在大规模代码库中安全、可靠地运行多个 agent？

这一需求的本质与容器化高度相似：隔离、资源管控、可复现。于是团队从 Docker Compose 的设计哲学中汲取灵感，打造了 agent-compose。项目的命名直接致敬了 Docker Compose，表达的是：同样简洁的声明式语法，同样强大的生命周期管理，只是管理对象从容器换成了 AI agent。

当前项目处于公开预览阶段（Public Preview），API 和部署默认值仍可能调整，官方建议用于实验和本地开发，而非生产环境。

核心功能：从"单 agent 工具"到"多 agent 编排平台"

声明式配置：agent-compose.yml

用户通过一个 YAML 文件定义项目和 agent：

services:
  coder:
    image: ghcr.io/chaitin/agent-compose/claude:latest
    provider: claude
    workspace: ./projects/myapp
    triggers:
      - type: cron
        cron: "0 9 * * *"
    env:
      MODEL: sonnet-4

  reviewer:
    image: ghcr.io/chaitin/agent-compose/codex:latest
    provider: codex
    workspace: ./projects/myapp
    triggers:
      - type: event
        source: coder
        event: completed

这种声明式模型的威力在于：整个多 agent 系统的状态由这一份文件驱动，agent-compose up 即启动全部 agent，agent-compose down 即全部停止，agent-compose ps 查看运行状态——和 Docker Compose 的体验如出一辙。

多 Provider 支持

agent-compose 不绑定任何单一 AI 服务商，目前支持的 agent provider 包括：

Provider	底层 CLI	说明
Claude Code	`claude`	Anthropic 官方 CLI
Codex	`codex`	OpenAI coding agent
Gemini	`gemini`	Google Gemini CLI
OpenCode	`opencode`	开源 agent CLI
Pi	`pi`	另一个开源选项

每种 provider 在 pkg/llms/ 下都有对应的 facade 实现（如 codex_facade.go、anthropic_credential.go），保证了各 provider 接口的统一封装。

三种运行时隔离

agent-compose 提供了三个层次的运行时隔离选择：

docker（默认）：每个 agent 运行在独立的 Docker 容器中，依赖 Docker 的 Namespace 和 Cgroup 隔离。
boxlite（microVM）：基于轻量级虚拟机，提供比容器更强的隔离级别，适合对安全要求更高的场景。
microsandbox：超轻量沙箱，适合快速实验场景。

在 pkg/driver/ 目录下可以找到这些 runtime driver 的具体实现。boxlite_runtime.go 负责 microVM 模式的生命周期管理。

调度器：从 cron 到事件驱动

agent 的触发方式支持四种模式：

cron：标准 cron 表达式，如每天早上 9 点自动运行
interval：按固定时间间隔重复
timeout：单次限时运行
event：事件触发，例如"当 coder agent 完成时自动启动 reviewer agent"

更强大的特性是支持内联 JavaScript scheduler 脚本，可以写任意复杂度的调度逻辑。

事件触发与 Webhook

agent-compose 内置了事件总线。在 pkg/events/ 目录下可以找到事件相关的领域模型和处理器。agent 之间可以互相触发，支持 webhook 回调，实现与外部 CI/CD 系统的联动。

MCP Server 集成

MCP（Model Context Protocol）是 AI 工具生态的新兴标准。agent-compose 在 pkg/skills/ 和配置层面原生支持 MCP server 的接入，每个 agent 可以独立挂载不同的 MCP server 组合，实现差异化的工具集。

Workspace 供给

agent 的工作空间（workspace）可以从本地目录或 Git 仓库初始化。pkg/workspaces/ 目录处理 workspace 的创建、拉取和管理，保证每个 agent 获得一致且可复现的工作环境。

Runtime LLM Facade（安全关键）

这是 agent-compose 最体现安全意识的设计：API key 始终留在 daemon 进程内，不传入 guest 容器。

在 pkg/llms/ 的 facade 层（如 codex_facade.go）中，daemon 持有真实的 provider API key，对 guest 容器暴露的是一个代理端点。Guest 中的 agent CLI 以为自己直连 provider，实际上所有请求都经过 daemon 转发，key 从未离开主机。

这解决了企业场景中一个非常实际的痛点：不想让 API key 进入任何第三方 agent 的进程空间。

Web UI（可选）

Web UI 是一个独立服务（agent-compose-ui 仓库），不随 daemon 默认启动，需要使用 --profile with-ui 或在 docker-compose 中激活对应 profile 才会上线。它通过 v2 Connect API 与 daemon 通信，提供图形化的 agent 状态查看、日志浏览和运行管理。

技术架构：Go + gRPC + Connect + SQLite

从 go.mod 可以看出项目的技术选型：

语言：Go 1.26.2，编译为单个可执行文件，部署简单
gRPC + Connect：使用 ConnectRPC 框架同时暴露 gRPC 和 HTTP/1.1 API（v1/v2 两个版本）
Docker SDK：github.com/docker/docker v28.5.1，直接操作 Docker API 管理容器
Web 框架：Labstack Echo v4，提供 HTTP 中间件和路由
数据库：SQLite（modernc.org/sqlite），持久化项目和运行状态，无需额外部署
依赖注入：samber/do/v2 + samber/mo，代码模块化程度高
YAML 解析：gopkg.in/yaml.v3，解析 agent-compose.yml
定时任务：robfig/cron/v3，支撑 scheduler 功能

核心代码组织（pkg/ 目录）：

包	职责
`compose/`	agent-compose.yml 解析、规范化
`driver/`	运行时 driver（docker/boxlite/microsandbox）
`llms/`	各 provider 的 LLM facade
`sandboxes/`	沙箱生命周期管理
`schedulers/`	调度器实现
`events/`	事件总线
`storage/`	SQLite 持久化
`capabilities/`	Agent 能力注册与发现
`imagecache/`	Guest 镜像缓存管理
`agentcompose/`	Daemon 应用主入口

上手体验：两条路径的权衡

方式 A（推荐）—— 一键安装脚本：

curl -fsSL https://github.com/chaitin/agent-compose/releases/download/installer-latest/install.sh | bash

脚本会自动检测 Linux 架构、拉取镜像、配置 docker-compose，启动后打印 admin 密码和 Web UI 地址。适合服务器部署场景。

方式 B（开发者路径）—— 源码构建：

task build
agent-compose daemon

适合需要在本地修改代码或调试 CLI 工作流的开发者。

争议与局限

生产就绪度：官方明确表示"尚未达到稳定生产平台"，API 可能变更，不建议直接用于核心业务系统。
Provider 依赖：支持的 agent CLI（如 Claude Code）本身是闭源商业工具，agent-compose 只是封装了一层调度。
学习成本：虽然借鉴了 Docker Compose 的心智模型，但 agent 编排比容器编排更复杂（状态一致性、agent 间通信、成本控制），实际使用需要理解多层抽象。
多运行时支持尚未成熟：boxlite 和 microsandbox 作为 experimental 特性，生产可用性有待验证。

行业意义与趋势

agent-compose 代表了一个正在兴起的产品方向：AI agent 的容器化。就像容器解决了"这段代码在我机器上能跑"的问题，agent 编排工具试图回答："这个 AI agent 在我的基础设施上可预测地执行"。

随着 Claude Code、Copilot Workspace 等 coding agent 工具的普及，对多 agent 协作、任务调度、安全隔离的需求会持续增长。agent-compose 的出现填补了开源生态中这一层的空白，其声明式配置理念对后续工具链设计有重要参考价值。

截至目前项目已获得约 216 个 GitHub stars，虽然体量不大，但背后的思路——将 Docker Compose 的成功经验迁移到 AI 基础设施——值得持续关注。

agent-compose：给 AI coding agent 造一个"Docker Compose"

痛点场景：当你需要同时跑多个 AI agent 时

假设你正在开发一个复杂的多智能体系统：需要 Claude Code 写代码、Codex 做代码审查、Gemini 处理文档生成。你会怎么做？

chaitin org avatar

项目背景：来自安全厂商的开源实验

当前项目处于公开预览阶段（Public Preview），API 和部署默认值仍可能调整，官方建议用于实验和本地开发，而非生产环境。

核心功能：从"单 agent 工具"到"多 agent 编排平台"

声明式配置：agent-compose.yml

用户通过一个 YAML 文件定义项目和 agent：

services:
  coder:
    image: ghcr.io/chaitin/agent-compose/claude:latest
    provider: claude
    workspace: ./projects/myapp
    triggers:
      - type: cron
        cron: "0 9 * * *"
    env:
      MODEL: sonnet-4

  reviewer:
    image: ghcr.io/chaitin/agent-compose/codex:latest
    provider: codex
    workspace: ./projects/myapp
    triggers:
      - type: event
        source: coder
        event: completed

多 Provider 支持

agent-compose 不绑定任何单一 AI 服务商，目前支持的 agent provider 包括：

Provider	底层 CLI	说明
Claude Code	`claude`	Anthropic 官方 CLI
Codex	`codex`	OpenAI coding agent
Gemini	`gemini`	Google Gemini CLI
OpenCode	`opencode`	开源 agent CLI
Pi	`pi`	另一个开源选项

每种 provider 在 pkg/llms/ 下都有对应的 facade 实现（如 codex_facade.go、anthropic_credential.go），保证了各 provider 接口的统一封装。

三种运行时隔离

agent-compose 提供了三个层次的运行时隔离选择：

docker（默认）：每个 agent 运行在独立的 Docker 容器中，依赖 Docker 的 Namespace 和 Cgroup 隔离。
boxlite（microVM）：基于轻量级虚拟机，提供比容器更强的隔离级别，适合对安全要求更高的场景。
microsandbox：超轻量沙箱，适合快速实验场景。

在 pkg/driver/ 目录下可以找到这些 runtime driver 的具体实现。boxlite_runtime.go 负责 microVM 模式的生命周期管理。

调度器：从 cron 到事件驱动

agent 的触发方式支持四种模式：

cron：标准 cron 表达式，如每天早上 9 点自动运行
interval：按固定时间间隔重复
timeout：单次限时运行
event：事件触发，例如"当 coder agent 完成时自动启动 reviewer agent"

更强大的特性是支持内联 JavaScript scheduler 脚本，可以写任意复杂度的调度逻辑。

事件触发与 Webhook

MCP Server 集成

Workspace 供给

Runtime LLM Facade（安全关键）

这是 agent-compose 最体现安全意识的设计：API key 始终留在 daemon 进程内，不传入 guest 容器。

这解决了企业场景中一个非常实际的痛点：不想让 API key 进入任何第三方 agent 的进程空间。

Web UI（可选）

技术架构：Go + gRPC + Connect + SQLite

从 go.mod 可以看出项目的技术选型：

语言：Go 1.26.2，编译为单个可执行文件，部署简单
gRPC + Connect：使用 ConnectRPC 框架同时暴露 gRPC 和 HTTP/1.1 API（v1/v2 两个版本）
Docker SDK：github.com/docker/docker v28.5.1，直接操作 Docker API 管理容器
Web 框架：Labstack Echo v4，提供 HTTP 中间件和路由
数据库：SQLite（modernc.org/sqlite），持久化项目和运行状态，无需额外部署
依赖注入：samber/do/v2 + samber/mo，代码模块化程度高
YAML 解析：gopkg.in/yaml.v3，解析 agent-compose.yml
定时任务：robfig/cron/v3，支撑 scheduler 功能

核心代码组织（pkg/ 目录）：

包	职责
`compose/`	agent-compose.yml 解析、规范化
`driver/`	运行时 driver（docker/boxlite/microsandbox）
`llms/`	各 provider 的 LLM facade
`sandboxes/`	沙箱生命周期管理
`schedulers/`	调度器实现
`events/`	事件总线
`storage/`	SQLite 持久化
`capabilities/`	Agent 能力注册与发现
`imagecache/`	Guest 镜像缓存管理
`agentcompose/`	Daemon 应用主入口

上手体验：两条路径的权衡

方式 A（推荐）—— 一键安装脚本：

curl -fsSL https://github.com/chaitin/agent-compose/releases/download/installer-latest/install.sh | bash

脚本会自动检测 Linux 架构、拉取镜像、配置 docker-compose，启动后打印 admin 密码和 Web UI 地址。适合服务器部署场景。

方式 B（开发者路径）—— 源码构建：

task build
agent-compose daemon

适合需要在本地修改代码或调试 CLI 工作流的开发者。

争议与局限

生产就绪度：官方明确表示"尚未达到稳定生产平台"，API 可能变更，不建议直接用于核心业务系统。
Provider 依赖：支持的 agent CLI（如 Claude Code）本身是闭源商业工具，agent-compose 只是封装了一层调度。
学习成本：虽然借鉴了 Docker Compose 的心智模型，但 agent 编排比容器编排更复杂（状态一致性、agent 间通信、成本控制），实际使用需要理解多层抽象。
多运行时支持尚未成熟：boxlite 和 microsandbox 作为 experimental 特性，生产可用性有待验证。

行业意义与趋势

截至目前项目已获得约 216 个 GitHub stars，虽然体量不大，但背后的思路——将 Docker Compose 的成功经验迁移到 AI 基础设施——值得持续关注。