Home

Maestro Developer Wiki

Maestro is a self-hostable, BYOK (Bring Your Own Key) AI-agent orchestration platform. A user submits a single prompt; an Orchestrator classifies it, routes it to a domain Main Agent, which decomposes the work and coordinates Subagents, an optional Reviewer enforces quality, and a Synthesis step streams the final answer back over WebSocket.

This wiki is the developer-facing reference. It documents the current state of the code — including behavior that the top-level README.md has not yet caught up with. Where they differ, this wiki is authoritative (see Billing-and-Quota for the corrected pricing).

---

What Maestro is

• Multi-layer agent hierarchy — Orchestrator → Main Agent → Subagents → optional Reviewer → Synthesis, executed by a durable engine that checkpoints every step and resumes after a crash.
• BYOK across many providers — 12 chat-capable LLM adapters (Ollama, OpenAI, Anthropic, Gemini, Groq, DeepSeek, Mistral, xAI, OpenRouter, Together, Perplexity, custom) plus service connectors. Keys are AES-256-GCM encrypted and never returned to the browser.
• Free/offline path — the whole flow runs locally at zero cost via Ollama (qwen3.5:9b) for chat and nomic-embed-text for embeddings.
• RAG memory — per-user conversation memory and uploaded document chunks in Qdrant, injected into agent prompts at task start.
• Marketplace — community agent teams, published behind a mandatory security scan, installable in one click.
• Real-time UX — live task graph, streamed synthesis, and human-in-the-loop questions over WebSocket.

Architecture at a glance

flowchart TD
    U[User Prompt] --> O[Orchestrator<br/>routing only]
    O --> M[Main Agent<br/>domain expert, plans subtasks]
    M --> S1[Subagent<br/>atomic task]
    M --> S2[Subagent<br/>atomic task]
    S1 --> R[Reviewer<br/>optional, weighted rubric]
    S2 --> R
    R --> SY[Synthesis<br/>streamed to user]
    SY --> U

Loading

The engine is durable: every step (ROUTE, EXECUTE, FINALIZE) is checkpointed in PostgreSQL, leased with a heartbeat, and reconciled on restart, so a task never hangs in running after a crash. See Agent-Orchestration for the full pipeline.

Where to start

If you want to…	Read
Understand the system top-down	Architecture-Overview
Follow a task through the agents	Agent-Orchestration
Find an HTTP endpoint	API-Reference
Understand the data model	Database-Schema
Run it locally	Development-Setup
Deploy it	Deployment
Add a provider or understand BYOK	LLM-Providers-and-BYOK
Review the security model	Security

Full page map

• Overview — Architecture-Overview, Agent-Orchestration
• Backend — Backend-Reference, API-Reference, Database-Schema, LLM-Providers-and-BYOK, Security, Billing-and-Quota, RAG-and-Memory, Realtime-and-WebSockets
• Frontend — Frontend-Reference
• Operations — Configuration, Development-Setup, Deployment
• Project — Contributing-and-License, Roadmap

Tech stack

Layer	Technology
Frontend	Next.js 16 (App Router), React 19, TypeScript (strict), Zustand 5, Tailwind 3.4
Backend	FastAPI (async), Python 3.11
Relational DB	PostgreSQL 16 (SQLAlchemy 2.0 async)
Document DB	MongoDB 7 (Motor)
Vector DB	Qdrant
Cache / rate-limit	Redis 7
Local models	Ollama (Qwen3.5 chat, nomic-embed-text embeddings)
Reverse proxy	Caddy 2 (single origin, auto-TLS)

License

Maestro is released under the Sustainable Use License v1.0 (fair-code, the same model as n8n): source-available, free to self-host and modify, but you may not offer it to third parties as a hosted/managed service. See Contributing-and-License.