multi-agent-collab

multi-agent-collab

Architecture for running multiple AI coding agents (Claude Code, Codex CLI, OpenClaw or any OpenAI-compatible gateway) each in their own Docker container, with:

• One repo clone shared via /opt/ bind mount — never cloned N times
• Inter-agent SSH for task delegation and status exchange
• Named volumes for each agent's private state
• A coordinator container that routes tasks and aggregates results

1) Mental Model

Host /opt/myrepo (single git clone — read/write by coordinator, read-only by workers)
      │
      ├── agent-coordinator (Claude Code) — orchestrates, assigns tasks, merges
      │       ├── SSH → agent-codex
      │       ├── SSH → agent-openclaw
      │       └── bind: /opt/myrepo (read-write)
      │
      ├── agent-codex (OpenAI Codex CLI)
      │       ├── SSH ← coordinator (receives task specs)
      │       └── bind: /opt/myrepo (read-only or scoped subdir)
      │
      └── agent-openclaw (OpenClaw gateway)
              ├── SSH ← coordinator
              └── bind: /opt/myrepo (read-only or scoped subdir)

Key rules:

1. git clone happens once on the host at /opt/myrepo
2. Containers bind-mount that directory — no per-container clones
3. Only the coordinator (or a dedicated repo-sync sidecar) does git pull / git push
4. Workers write to named volumes for their private scratch state
5. Agents communicate via SSH, not shared memory or Docker networks directly

2) docker-compose Topology

# docker-compose.agents.yml
services:

  # ── Coordinator ────────────────────────────────────────────────────────
  agent-coordinator:
    build:
      context: ./agents/coordinator
      dockerfile: Dockerfile
    container_name: agent-coordinator
    restart: unless-stopped
    volumes:
      - /opt/myrepo:/opt/myrepo                  # read-write (does git ops)
      - coordinator-state:/home/agent/.local      # private state
      - /opt/keys:/opt/keys:ro                    # SSH keys to reach workers
    environment:
      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
      AGENT_CODEX_HOST: agent-codex
      AGENT_OPENCLAW_HOST: agent-openclaw
    networks:
      - agents
    extra_hosts:
      - "host.docker.internal:host-gateway"

  # ── Codex Worker ───────────────────────────────────────────────────────
  agent-codex:
    build:
      context: ./agents/codex
      dockerfile: Dockerfile
    container_name: agent-codex
    restart: unless-stopped
    volumes:
      - /opt/myrepo:/opt/myrepo:ro               # read-only — no direct git push
      - codex-workspace:/workspace               # private scratch volume
      - /opt/keys/codex_authorized_keys:/home/agent/.ssh/authorized_keys:ro
    environment:
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
      REPO_PATH: /opt/myrepo
    networks:
      - agents

  # ── OpenClaw Worker ────────────────────────────────────────────────────
  agent-openclaw:
    build:
      context: ./agents/openclaw
      dockerfile: Dockerfile
    container_name: agent-openclaw
    restart: unless-stopped
    volumes:
      - /opt/myrepo:/opt/myrepo:ro
      - openclaw-workspace:/workspace
      - /opt/keys/openclaw_authorized_keys:/home/agent/.ssh/authorized_keys:ro
    environment:
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
      OPENCLAW_BASE_URL: "${OPENCLAW_BASE_URL}"
    networks:
      - agents

networks:
  agents:
    driver: bridge

volumes:
  coordinator-state:
  codex-workspace:
  openclaw-workspace: