stack/docker/README.md

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

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

Required environment variables

• DATABASE_URL
• MOSAIC_SECRET_KEY
• DATABASE_PASSWORD

Use docker/.env.example as a starting point.

Architecture overview

See the design doc: 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.