# MAESTRO: a self-hosted four-agent research desk built on pgvector

> An AGPL-3.0 alpha that splits research into Planning, Research, Reflection and Writing agents, keeps documents and embeddings in PostgreSQL with pgvector, and resumes interrupted missions from checkpoints instead of starting over.

**murtaza-nasir/maestro** — MAESTRO is an AI-powered research application designed to streamline complex research tasks.

- Repository: https://github.com/murtaza-nasir/maestro
- Stars: 1,492 · Forks: 145
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/murtaza-nasir-maestro

## Four agents in sequence rather than one long prompt

The core feature list names a Multi-Agent Research System with Planning, Research, Reflection and Writing agents working in concert. That ordering is the design, and it is the reason the tool exists rather than a chat window bolted to a document store.

Planning decomposes a mission into work. Research executes against documents and the web. Reflection examines the gathered material before anything is composed, which is the stage that catches a thin evidence base early rather than at review time. Writing produces the report. The README's screenshots give this away more than the feature list does, since there are separate views for mission tracking, research transparency, agent reflection, AI-generated notes and the finished report, rather than one chat transcript with everything interleaved.

The debug environment variables confirm these are distinct subsystems rather than one prompt with different framings. The compose file ships `DEBUG_MESSENGER=true`, `MESSENGER_SIMPLE_PROMPT=true`, `DEBUG_PLANNING=true` and `DEBUG_REFLECTION=true` as defaults, with `MAX_WORKER_THREADS` defaulting to 10. So each stage can be inspected in isolation, and the research phase fans out across a bounded worker pool.

Worth noting that `MESSENGER_SIMPLE_PROMPT` is on by default, which reads as a deliberately plainer interaction mode rather than a debugging leftover. The documentation is the place to find out what turning it off changes.

## pgvector and BGE-M3 as the retrieval substrate

Document handling is the other half. MAESTRO accepts PDF, Word and Markdown, groups documents, and supports semantic search across them. The retrieval pipeline is described as dual BGE-M3 embeddings stored in PostgreSQL with pgvector, and the compose file backs that up by using the `pgvector/pgvector:pg15` image rather than stock Postgres, with an `init-db/` directory mounted into the container entrypoint so extensions and schema are created on first boot.

Using one database for documents, embeddings and vectors is the decision that shapes everything else operationally. A separate vector store would add a service to back up and a consistency problem between the two. Here there is one volume, `postgres-data`, and one thing to reason about. The cost is that vector search and relational queries share the same process, so a large embedding table will eventually compete with ordinary queries for the same memory.

Models are cached on disk rather than pulled on every run, with named volumes mounting into `/root/.cache/huggingface` and `/root/.cache/datalab`, plus a bind mount for `reports/` output and one for application data. The Hugging Face cache mount matters on an air-gapped or metered host: once the embedding model is resident, document ingestion does not re-download it.

Web search is pluggable across four providers, Tavily, LinkUp, Jina and SearXNG. The last of those is a self-hosted metasearch instance, so a fully local deployment is possible if you run one. Local models are supported too, through any OpenAI-compatible API, which is what makes this usable on hardware you control rather than a hosted provider.

## Starting the stack with setup-env.sh and docker compose

Prerequisites are modest for a self-hosted tool with an embedding pipeline: Docker with Compose v2.0 or newer, 16GB of RAM as a minimum with 32GB recommended, 30GB of free disk, and API keys for at least one AI provider.

```bash
git clone https://github.com/murtaza-nasir/maestro.git
cd maestro
./setup-env.sh    # Linux/macOS
docker compose up -d
docker compose logs -f maestro-backend
```

The setup script copies `.env.example` into place and is mirrored as `setup-env.ps1` for Windows PowerShell. The README warns that first startup takes 5 to 10 minutes, which is model download and embedding warm-up rather than a hang. A `detect_gpu.sh` script in the tree handles NVIDIA detection, and `start.sh` and `stop.sh` wrap the compose calls for people who do not want to remember them.

Nginx is the single entry point, published on `MAESTRO_PORT` with a default of 80, and the compose file marks backend and frontend as its dependencies. The `.env.example` keeps direct backend and frontend access settings commented out and says most users should leave them that way, which is a sensible default: one port to firewall instead of three.

Hardware placement is per service rather than global:

```ini
MAESTRO_PORT=80
BACKEND_GPU_DEVICE=0
DOC_PROCESSOR_GPU_DEVICE=0
CLI_GPU_DEVICE=0
```

Separate device IDs for the backend, the document processor and the CLI mean you can put ingestion and inference on different cards. If you have no GPU at all, the CPU path is a separate compose file:

```bash
docker compose -f docker-compose.cpu.yml up -d
```

The README describes the default login as `admin` with the password found in `.env`, which is better than a published default password but still means the credential lives in a file on disk. Rotate it before the instance is reachable by anyone else.

## Checkpoint recovery is what makes the alpha label tolerable

Release 0.1.8 is titled Mission Resilience & Document Intelligence Update and its contents are all about not losing work: intelligent mission resume with complete checkpoint preservation, writing phase resume support, document reprocessing and re-embedding capabilities, and fixed progress indicators. The 0.1.9 alpha then fixed pause and resume with proper checkpoint handling.

That sequence tells you something real about how the tool behaves. A mission in MAESTRO is long enough to be interrupted, and before 0.1.8 it evidently could be interrupted badly enough to lose its place. For research workflows this is the feature that matters most, because the expensive part is the provider calls and the embedding work, not the writing. Being able to stop a run and resume at the writing phase rather than re-running the whole mission changes what the tool is worth.

The document side of that release is also practical. Reprocessing and re-embedding matter when you change embedding models or fix a broken parser, and arXiv fetching by paper identifier covers the common case of dropping a specific paper into a library.

One factual wrinkle worth flagging. The README dates version 0.1.9 as October 3, 2025 and 0.1.8 as September 26, 2025, while the release timestamps for those tags are 2025-10-04 and 2025-09-27 respectively. Both are off by exactly one day, consistent with the release times falling just after midnight UTC. If you are pinning a version for reproducibility, trust the release timestamp over the prose date.

## Azure OpenAI and the missing /models endpoint

Version 0.1.10 added Azure OpenAI support including GPT-5 models with automatic parameter handling, plus a manual model entry toggle. Both changes come from the same root cause: providers differ in how much of the OpenAI surface they actually implement.

Automatic model discovery means fetching a list, which is what a `/models` endpoint is for. Azure deployments do not generally expose that in a compatible way, so a client that only discovers will report no models available for a perfectly working deployment. The manual entry toggle exists for exactly that case. This is a small feature that tells you something about the user base: people are pointing this at enterprise gateways and self-hosted proxies, not just api.openai.com.

The other two fixes in 0.1.10 are user-visible and both are the kind of bug that erodes trust fast. A 401 from an external provider was logging users out, which conflates a bad key upstream with a failed session locally. Mission settings now persist correctly across server restarts with what the notes call proper priority handling, so configuration no longer silently resets.

Release 0.1.9 also replaced passlib with a maintained libpass fork and fixed bcrypt compatibility for authentication. That is the item to look up before you expose an instance, since it touches password hashing rather than the research pipeline. Reading a security release note about a dependency swap is a reasonable use of five minutes.

## AGPL-3.0, a 16GB floor, and what the evaluation directory implies

The project is licensed AGPL-3.0, stated in the README badge, in the repository metadata and in a `LICENSE` file at the root. For a tool you host on your own hardware and use internally, that is workable. For a hosted service where users interact over a network, the copyleft obligation attaches to modified versions offered as a service, which is worth understanding before you put it behind a login for other people. That is a licensing question rather than an engineering one, so treat it as one to check with whoever owns that decision.

The tree suggests more evaluation work than the README advertises. Alongside `tests/` and an `evaluation/` directory there are `VERIFIER_AND_MODEL_FINDINGS.md` and two heatmap images, one per category set and one for performance metrics. Heatmaps of model performance across categories is the shape of a multi-provider comparison, which fits the four-provider web search support and the manual model entry work. The documentation site also links an Example Reports page with sample outputs from various models. None of that is quantified in the README, so treat it as evidence that the author ran comparisons and not as a benchmark you can cite.

The maintenance picture in plain terms: the repository is not archived, the last push was on 2026-04-16, and the most recent published release is v0.1.10-alpha from 2025-10-12. Every tag carries the alpha suffix and there is no version 1.0. The docs are thorough, split into quick start, installation, configuration, user guide, example reports and troubleshooting, with a mkdocs configuration and a GitHub Pages site. The gap between documentation depth and release maturity is the thing to keep in view: this is well-documented software that has not yet committed to a stable API.

## Conclusion

MAESTRO is built for the case where research takes longer than one session and the document set is yours. Its distinguishing pieces are checkpointed mission resume, so an interrupted run continues instead of restarting, and a reflection stage that gets a look at the work before writing begins. The price is real infrastructure: a 16GB RAM floor, 30GB of disk, and a Postgres image with the vector extension baked in, all behind one nginx entry point. The version tag is the other thing to read carefully. The repository is at 0.1.10-alpha, every published release carries the alpha suffix, and the last push was on 2026-04-16 with the newest release dated 2025-10-12. Check the release notes for the passlib to libpass swap before exposing an instance to anyone, since authentication internals have already moved once. Start with the CPU compose file, put documents in, and let one mission run end to end before adding a GPU.

## FAQ

### What is MAESTRO and who is it for?

MAESTRO is a self-hosted AI research application that runs a mission through four cooperating agents, Planning, Research, Reflection and Writing, and produces a cited report from your own documents plus web sources. It suits people doing multi-session research over a private document set, who want the data to stay on their own hardware and can supply 16GB of RAM and an AI provider key.

### How do you install and start MAESTRO?

Clone the repository, run `./setup-env.sh` on Linux or macOS or `setup-env.ps1` on Windows, then `docker compose up -d`. First startup takes 5 to 10 minutes while models download, and the app is served by nginx on port 80 by default. On a machine with no GPU, use `docker compose -f docker-compose.cpu.yml up -d` instead.

### Can MAESTRO run on a local model instead of a hosted API?

Yes. The core features list local LLM support through an OpenAI-compatible API, so any server exposing that interface can back the agents. Web search is also self-hostable, since SearXNG is one of the four supported search providers alongside Tavily, LinkUp and Jina.

### What happens if a MAESTRO mission is interrupted?

Since version 0.1.8 missions resume from checkpoints with state preserved, including a resume path for the writing phase specifically, and 0.1.9 fixed pause and resume handling along with the round counter and activity log. Documents can also be reprocessed and re-embedded without starting over.

### What license is MAESTRO released under?

AGPL-3.0, according to the README badge, the repository metadata and the LICENSE file. Self-hosting for your own use is straightforward; the copyleft terms matter more if you offer it to other people as a network service, so check the license text against your situation.

## Sources

- [Issues](https://github.com/murtaza-nasir/maestro/issues)
- [License: AGPL-3.0](https://github.com/murtaza-nasir/maestro/blob/main/LICENSE)
- [murtaza-nasir/maestro on GitHub](https://github.com/murtaza-nasir/maestro)
- [README](https://github.com/murtaza-nasir/maestro/blob/main/README.md)
- [Releases](https://github.com/murtaza-nasir/maestro/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/murtaza-nasir-maestro