MongoDB

What it stores

Users, organizations, projects, tasks and their events, the audit log, capabilities, secrets (encrypted), worker records and settings. Task claims and leases are atomic MongoDB updates, so exactly one worker can win a claim — the queue only signals.

Versions

MongoDB 7 and 8 are tested (Docker Compose ships MongoDB 7; the backup drill ran on 8.3). Services that call themselves MongoDB-compatible may lack features the platform uses, such as text indexes or $expr in updates; test them before relying on them. MongoDB Atlas is plain MongoDB.

Connection

Set MONGODB_URI, for example mongodb://mongo:27017/agent_orchestration in Docker Compose or an Atlas mongodb+srv://… URI.

Migrations

Indexes and data migrations run automatically at startup. Migrations take a lock, so several API instances can start at once.

During an outage

If MongoDB stops, the API stays up and answers with retryable errors, and /readyz reports 503. Workers keep running their tasks, buffer events on disk and retry state changes with the same idempotency ids; the task completes after MongoDB returns. This is covered by the core's chaos tests.

Retention

An hourly job purges old data according to retention settings. Active tasks are never purged.