Maestro v0.1.0

Maestro is a bring-your-own-key AI agent orchestration platform. One prompt goes in, an Orchestrator classifies the domain, a Main Agent decomposes the work, subagents execute atomic subtasks, an optional Reviewer enforces quality, and a synthesized answer comes out.

This is the first tagged release. Everything described below runs today from docker compose up, including a fully local, zero-cost path on Ollama.

Agent runtime

• Four-layer hierarchy. Orchestrator routes, Main Agent plans, subagents execute, Reviewer validates. Every contract between layers is structured JSON, never free text, and every loop carries an explicit bound (max_iterations, max_review_iterations, task_timeout_seconds).
• 15 built-in domain squads — software, finance, marketing, seo, searching, research, data, content, legal, education, social, community, opensource, local, general. Each ships a fixed specialist team; the Main Agent briefs the relevant members rather than inventing new ones. Effort scaling decides how many members actually run.
• Durable execution. Task state lives in PostgreSQL as checkpoints with leases, heartbeats and a reconciliation sweep, so a crashed worker resumes or finalizes instead of leaving a task stuck in running. Cancellation, human-in-the-loop questions and multi-worker coordination go over a Redis event bus.
• Quality controls. Deterministic pre-review validators, weighted review_criteria with hard_fail gates, hierarchical token budgets per wave and per call, context compaction, and partial failure surfaced as completed_with_warnings with a stated gap list rather than a silent pass.
• Failure honesty. A blank subagent answer is a failure, not a success. A fruitless web search self-heals through a bounded query ladder invisible to the tool budget. A hallucinated GitHub repo slug re-resolves through an anonymous probe and a search fallback, and the answer states which repository was actually read.

Bring your own key

• 67 providers — 25 chat brains and 42 service integrations. Every base URL was probed live before it shipped.
• Keys are encrypted with AES-256-GCM under a master key held only in the environment, and are never returned to the frontend; only provider and label are.
• Per-role model routing, so planning, execution, review and synthesis can run on different models behind one token counter.
• Cost accounting for 24 priced providers, surfaced per task and per trace span.

Tools

Seven executable tools: web_search, data_fetch, repo_intel, social_search, community_read, places_intel, and code_execution (off by default; enabling it requires mounting the Docker socket).

data_fetch runs on Scrapling with curl_cffi TLS impersonation and optional CSS-selector extraction. Every user- or model-supplied URL passes an SSRF guard, redirects are refused before the request when they point at an internal address, and fetched content is delimited, marked untrusted and injection-scanned before a model sees it.

A missing service key degrades rather than stopping the task: the tool is withheld, the squad falls back to web_search, and a mandatory data-coverage section states what could not be reached. repo_intel works with no key at all against GitHub's anonymous read quota.

Knowledge, marketplace, accounts

• RAG memory — per-user conversation embeddings and document chunks in Qdrant, retrieved at task start and injected into agent prompts. Memory is scoped per user and never crosses accounts.
• Marketplace — publish agent teams behind a mandatory security scan, one-click install, ratings and reviews, install trends, and a report queue backed by admin moderation with an audit log.
• Accounts and security — JWT with refresh-token rotation and reuse detection, TOTP 2FA with Argon2-hashed single-use recovery codes, session listing and revocation, email verification and password reset, and an explicit rate limit on every single route including WebSockets.
• Data rights — GDPR Article 17 erasure with a 30-day recovery window and a purge that clears MongoDB and Qdrant before the PostgreSQL row, plus Article 20 export. Legal pages ship for both GDPR and KVKK.

Billing and quota

Three plans — starter $5, pro $15, scale $50 per month, at 500K / 3M / 10M tokens. Quota is enforced solely through an append-only PostgreSQL ledger, written in the task's finally block on every terminal path including timeout and cancellation.

Only the mock payment provider is included in this repository. A real processor is one adapter file behind the existing PaymentProvider protocol.

Observability

First-party tracing with OpenTelemetry gen_ai.* attributes and per-span cost, a span waterfall in the UI, Sentry on both frontend and backend (fully off with zero egress when the DSN is empty), structured JSON logs with request ids, and /health plus /health/ready probes.

Deployment

Single-origin production topology behind Caddy, which means CORS disappears entirely and the frontend image stays domain-agnostic. Migrations run as a gated one-shot service, so a failed migration leaves the previous backend running. Tagged rollouts pass a health gate with automatic rollback to the previous tag. A backup script covers PostgreSQL, MongoDB and Qdrant with local and offsite retention.

Container images for this release:

ghcr.io/yigtwxx/maestro-backend:0.1.0
ghcr.io/yigtwxx/maestro-frontend:0.1.0

Tagged releases are built for linux/amd64 and linux/arm64.

Verification

Backend: 1013 tests passing, ruff check and ruff format --check clean. Frontend: type-check, lint and build clean. Migration head 0014_default_tracing_enabled. Dependency locks are hash-pinned and regenerated by CI on every pull request, which fails if a lock has drifted from its .in file.

Known limitations

• A hosted instance cannot reach an Ollama server on a user's own machine, because all LLM calls are made backend-side. Running the whole stack locally is the intended self-hosting path and stays free.
• Payments are mocked. BILLING_LIVE is false and both /terms and /pricing say so.
• The social_search, community_read and places_intel response parsers were written from documentation and have not been exercised against their live providers. They are defensive and degrade to "no results" on a shape mismatch, but the field names are unverified. Only repo_intel is verified live.
• Telegram community reading is structurally partial: the Bot API exposes recently delivered updates, never channel history. The result header says so.
• google_drive, gmail and shopify are stored-only. They need an OAuth connect flow rather than a single-key paste, so no tool consumes them yet.
• The deployment pipeline has not been exercised against a production host.

License

Sustainable Use License v1.0. The source is available to read, run and modify for your own use; reselling it as a commercial service to third parties is not permitted. See LICENSE and CONTRIBUTING.md.