# Mosaic Docker (Core Services)

This folder includes the Compose stack for **core Mosaic services only**:

- `mosaic-api`
- `mosaic-web`
- `postgres`

User OpenClaw containers are **not** defined in Compose. They are created and managed dynamically by the API's `ContainerLifecycleService` through Docker socket access.

## Start the stack

```bash
docker compose -f docker/mosaic-compose.yml up -d
```

## Required environment variables

- `DATABASE_URL`
- `MOSAIC_SECRET_KEY`
- `DATABASE_PASSWORD`

Use [`docker/.env.example`](./.env.example) as a starting point.

## Architecture overview

See the design doc: [`docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md`](../docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md)

`mosaic-agents` is an internal-only bridge network reserved for dynamically created user containers.

## OpenClaw entrypoint behavior

`docker/openclaw-entrypoint.sh` is intended for dynamically created user OpenClaw containers:

1. Validates required env vars (`MOSAIC_API_URL`, `AGENT_TOKEN`, `AGENT_ID`).
2. Fetches agent-specific OpenClaw config from Mosaic API internal endpoint.
3. Writes the config to `/tmp/openclaw.json`.
4. Starts OpenClaw gateway with `OPENCLAW_CONFIG_PATH=/tmp/openclaw.json`.

`docker/openclaw-healthcheck.sh` probes `http://localhost:18789/health` for container health.