Quick Start¶
Two commands, no build, no configuration. The published images run the whole stack behind a local reverse proxy.
git clone https://github.com/Yigtwxx/Maestro.git && cd Maestro
docker compose -f docker-compose.quickstart.yml up -d
Then open http://localhost:8080 and register.
The first run pulls the images and the embedding model, so give it a few minutes; afterwards
it starts in seconds. If something already owns port 8080, set MAESTRO_PORT=8090 in front
of the command — it moves the proxy and the generated links together.
The quickstart file is a trial environment, not a deployment
It uses fixed, publicly known credentials and binds only to 127.0.0.1. For anything
reachable from outside your machine, follow Deployment instead.
Make your account usable¶
Registration alone cannot start tasks: the platform gates task start on an active plan, and the bundled payment gateway is a mock. Make your account unmetered instead:
docker compose -f docker-compose.quickstart.yml exec backend \
python -m app.scripts.grant_admin --email you@example.com
This sets the admin role, marks the address verified, and seeds a plan — enough to use every feature locally.
Where is the verification email?
The default email provider is console, which writes the message to the backend log
rather than sending it. docker compose -f docker-compose.quickstart.yml logs backend
shows the verification and password-reset links.
Connect a model¶
Add a provider key under Settings → API Keys. Gemini's free tier needs no credit card and is the fastest way to a working task.
RAG embeddings already run locally, so no key is needed for conversation memory or document upload.
To run chat locally as well — no key anywhere in the pipeline:
docker compose -f docker-compose.quickstart.yml exec ollama ollama pull qwen3.5:9b
docker compose -f docker-compose.quickstart.yml restart backend
Now submit a prompt. Open the Architect view while it runs to watch the orchestrator route the task, the main agent plan it, and the subagents execute in parallel.
A local 9B model is a real model, with real limits
It works end to end, but it reasons slowly and will occasionally spend an entire output budget thinking and return nothing. Maestro reports that as a failed subtask rather than a silent success, so you will see it. A hosted provider key removes the ceiling.
Running from source¶
For development rather than a trial. Prerequisites: Docker (for Postgres, Mongo, Qdrant and Redis), Python 3.11+, Node.js 20+, and Ollama for the local model and embeddings.
The dev scripts bring the whole stack up in one terminal — infrastructure, then the backend
(virtualenv, dependencies, alembic upgrade head, marketplace seed, uvicorn), then the
frontend. Ctrl+C stops everything.
The backend serves on http://localhost:8000 (OpenAPI at /docs), the frontend on
http://localhost:3000.
Manual setup, step by step
# 1. Environment
cp .env.example .env # fill in JWT_SECRET and API_KEY_MASTER_KEY
openssl rand -hex 32 # JWT_SECRET
openssl rand -base64 32 # API_KEY_MASTER_KEY
# 2. Infrastructure
docker compose up -d # postgres, mongo, qdrant, redis
# 3. Local models
ollama serve # separate terminal
ollama pull qwen3.5:9b
ollama pull nomic-embed-text
# 4. Backend
cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate | macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload # http://localhost:8000
# 5. Frontend
cd frontend
npm install
npm run dev # http://localhost:3000
Verifying a change¶
CI runs both suites on every push and pull request to main. Locally:
cd backend && pytest && ruff check . && ruff format --check .
cd frontend && npm run lint && npm run type-check && npm run build
A change is done when all of those pass. See Contributing for the full standards, and Configuration for every environment variable.