# PRD: MS22 — Fleet Evolution (DB-Centric Agent Architecture)

## Metadata

- Owner: Jason Woltje
- Date: 2026-03-01
- Status: in-progress
- Design Doc: `docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md`

## Problem Statement

Mosaic Stack needs a multi-user agent fleet where each user gets their own isolated OpenClaw instance with their own LLM provider credentials and agent config. The system must be Docker-first with minimal environment variables and all configuration managed through the WebUI.

## Objectives

1. **Minimal bootstrap** — 2 env vars (`DATABASE_URL`, `MOSAIC_SECRET_KEY`) to start the entire stack
2. **DB-centric config** — All runtime config in Postgres, managed via WebUI
3. **Per-user isolation** — Each user gets their own OpenClaw container with own API keys, memory, sessions
4. **Onboarding wizard** — First-boot experience: breakglass admin → OIDC → LLM provider → agent config
5. **Settings UI** — Runtime management of providers, agents, and auth config
6. **Mosaic as gatekeeper** — Users never talk to OpenClaw directly; Mosaic proxies all requests
7. **Zero cross-user access** — Full container, volume, and DB isolation between users

## Security Requirements

- User A cannot access User B's API keys, chat history, or agent memory
- All API keys stored encrypted (AES-256-GCM) in database
- Breakglass admin always works as OIDC fallback
- OIDC config stored in DB (not env vars) — configured via settings UI
- Container-to-container communication blocked by default
- Admin cannot decrypt other users' API keys

## Phase 0: Knowledge Layer — COMPLETE

- Findings API (pgvector, CRUD, similarity search)
- AgentMemory API (key/value store)
- ConversationArchive API (pgvector, ingest, search)
- OpenClaw mosaic skill
- Session log ingestion pipeline

## Phase 1: DB-Centric Agent Fleet

### Phase 1a: DB Schema — COMPLETE

- SystemConfig, BreakglassUser, LlmProvider, UserContainer, SystemContainer, UserAgentConfig tables

### Phase 1b: Encryption Service — COMPLETE

- CryptoService (AES-256-GCM using MOSAIC_SECRET_KEY)

### Phase 1c: Internal Config API

- `GET /api/internal/agent-config/:id` — assembles openclaw.json from DB
- Auth: bearer token (container's own gateway token)
- Returns complete openclaw.json with decrypted provider credentials

### Phase 1d: Container Lifecycle Manager

- Docker API integration via `dockerode` npm package
- Start/stop/health-check/reap user containers
- Auto-generate gateway tokens, assign ports
- Docker socket access required (`/var/run/docker.sock`)

### Phase 1e: Onboarding API

- First-boot detection (`SystemConfig.onboarding.completed`)
- `POST /api/onboarding/breakglass` — create admin user
- `POST /api/onboarding/oidc` — save OIDC provider config
- `POST /api/onboarding/provider` — add LLM provider + test connection
- `POST /api/onboarding/complete` — mark done

### Phase 1f: Onboarding Wizard UI

- Multi-step wizard component
- Skip-able OIDC step
- LLM provider connection test

### Phase 1g: Settings API

- CRUD: LLM providers (per-user scoped)
- CRUD: Agent config (model assignments, personalities)
- CRUD: OIDC config (admin only)
- Breakglass password reset (admin only)

### Phase 1h: Settings UI

- Settings/Providers page
- Settings/Agent Config page
- Settings/Auth page (OIDC + breakglass)

### Phase 1i: Chat Proxy

- Route WebUI chat to user's OpenClaw container
- SSE streaming pass-through
- Ensure container is running before proxying (auto-start)

### Phase 1j: Docker Compose + Entrypoint

- Simplified compose (core services only — user containers are dynamic)
- Entrypoint: fetch config from API, write openclaw.json, start gateway
- Health check integration

### Phase 1k: Idle Reaper

- Cron job to stop inactive user containers
- Configurable idle timeout (default 30min)
- Preserve state volumes

## Future Phases (out of scope)

- Phase 2: Agent fleet standup (predefined agent roles)
- Phase 3: WebUI chat + task management integration
- Phase 4: Multi-LLM provider management UI (advanced)
- Team workspaces (shared agent contexts) — explicitly out of scope