# Mosaic Agent Fleet — Setup Guide

## Prerequisites

- Docker Swarm initialized on target host
- Mosaic Stack running (Postgres, Valkey on `mosaic-stack_internal` network)

## 1. Configure Environment Variables

Copy and fill in each agent's `.env` file:

```bash
cd docker/openclaw-instances

# Required for each agent:
# ZAI_API_KEY         — Your Z.ai API key (or other LLM provider key)
# OPENCLAW_GATEWAY_TOKEN — Unique bearer token per agent

# Generate unique tokens:
for agent in main projects research operations; do
  echo "OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)"
done
```

### Optional: Local Ollama

If you have an Ollama instance, add to any agent's `.env`:

```bash
OLLAMA_BASE_URL=http://your-ollama-host:11434
OLLAMA_MODEL=cogito  # or any model you have pulled
```

The entrypoint script will automatically inject the Ollama provider at startup.

### Optional: Override Default Model

```bash
OPENCLAW_MODEL=anthropic/claude-sonnet-4-6
```

## 2. Populate Config Volumes

Each agent needs its `.json.template` file in its config volume:

```bash
# Create config directories and copy templates
for agent in main projects research operations; do
  mkdir -p /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/
  cp openclaw-instances/mosaic-${agent}.json.template \
     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/openclaw.json.template
  cp openclaw-instances/entrypoint.sh \
     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/entrypoint.sh
done
```

## 3. Deploy

```bash
docker stack deploy -c docker/openclaw-compose.yml mosaic-agents
docker stack services mosaic-agents
```

## 4. First-Time Auth (if needed)

For providers requiring OAuth (e.g., Anthropic):

```bash
docker exec -it $(docker ps -q -f name=mosaic-main) openclaw auth
```

Follow the device-code flow in your browser. Tokens persist in the state volume.

You can also use the Mosaic WebUI terminal (xterm.js) for this.

## 5. Verify

```bash
# Check health
curl http://localhost:18789/health

# Test chat completions endpoint
curl http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"openclaw:main","messages":[{"role":"user","content":"hello"}]}'
```

## Environment Variable Reference

| Variable                 | Required | Description                                       |
| ------------------------ | -------- | ------------------------------------------------- |
| `ZAI_API_KEY`            | Yes\*    | Z.ai API key (\*or other provider key)            |
| `OPENCLAW_GATEWAY_TOKEN` | Yes      | Bearer token for this agent (unique per instance) |
| `OPENCLAW_MODEL`         | No       | Override default model (default: `zai/glm-5`)     |
| `OLLAMA_BASE_URL`        | No       | Ollama endpoint (e.g., `http://10.1.1.42:11434`)  |
| `OLLAMA_MODEL`           | No       | Ollama model name (default: `cogito`)             |