# Mosaic Agent Fleet

Multi-agent deployment for Mosaic Stack using OpenClaw containers on Docker Swarm.

## Architecture

Each agent runs as an isolated OpenClaw Gateway instance with its own:

- **Workspace** — persistent volume for agent files and memory
- **State** — persistent volume for auth tokens and sessions
- **Config** — template rendered at startup from environment variables

Agents communicate with the Mosaic API via the OpenAI-compatible
`/v1/chat/completions` endpoint. The Mosaic WebUI routes chat requests
to agents through the `OpenClawGatewayModule`.

## Default Agent Roles

| Agent             | Role         | Description                                 |
| ----------------- | ------------ | ------------------------------------------- |
| mosaic-main       | Orchestrator | User-facing gateway, routes to other agents |
| mosaic-projects   | Developer    | Implementation, coding, PRs                 |
| mosaic-research   | Research     | Web search, analysis, discovery             |
| mosaic-operations | Operations   | Monitoring, health checks, alerts           |

> **Models and providers are configured per-deployment** via environment
> variables and the Mosaic Settings UI — not hardcoded in these files.
> See the [Setup Guide](openclaw-instances/README.md) for env var reference.

## Prerequisites

- Docker Swarm initialized on target host
- Mosaic Stack running (`mosaic-stack_internal` network available)
- At least one LLM provider API key (Z.ai, OpenAI, Anthropic, etc.)

## Quick Start

1. **Configure** — Fill in `docker/openclaw-instances/*.env` files
2. **Deploy** — `docker stack deploy -c docker/openclaw-compose.yml mosaic-agents`
3. **Auth** — If needed, run `openclaw auth` inside a container (or via Mosaic terminal)
4. **Verify** — `docker stack services mosaic-agents`

See [openclaw-instances/README.md](openclaw-instances/README.md) for detailed setup.

## Future: Onboarding Wizard

Model assignments, provider configuration, and agent customization will be
managed through the Mosaic WebUI onboarding wizard and Settings pages (MS22-P4).
Until then, use environment variables per the README.