Configuration

Configuration

All backend settings are Settings fields in backend/app/core/config.py (pydantic-settings), overridable via environment or .env. The frontend reads a small set of server-only runtime vars. Dev defaults live in .env.example; production in .env.prod.example.

At boot, a production-secret guard rejects placeholder/weak secrets (JWT or master key < 32 bytes, placeholder values, a missing Resend key when EMAIL_PROVIDER=resend) so a misconfigured prod deploy fails fast instead of running insecure.

Backend environment

App & observability

Var	Default	Notes
ENVIRONMENT	development	production disables Swagger/redoc/openapi.
LOG_LEVEL	INFO
LOG_FORMAT	text	json in prod (structured, one object per line).
SENTRY_DSN	(empty)	Empty = Sentry fully off, zero egress.
SENTRY_TRACES_SAMPLE_RATE	0.0
SENTRY_ENVIRONMENT	(empty)	Falls back to ENVIRONMENT.
TRACING_ENABLED	—	Own trace infra; disabled = zero overhead.
TRACE_RETENTION_DAYS	30	TTL on trace_spans.

Databases

Var	Default	Notes
POSTGRES_URL	postgresql+asyncpg://maestro:maestro@localhost:5433/maestro	Port 5433 in dev (Windows often owns 5432).
MONGODB_URL	mongodb://localhost:27017/maestro	Prod adds ?authSource=admin.
MONGODB_DB_NAME	maestro
QDRANT_URL	http://localhost:6333
QDRANT_API_KEY	(empty)	Required in prod.

Rate limiting

Var	Default	Notes
REDIS_URL	(empty)	Empty = in-process buckets (single-worker dev/test).
RATE_LIMIT_ENABLED	true
TRUST_PROXY_HEADERS	false	true only behind a proxy that sets X-Forwarded-For (e.g. Caddy). See Security.

Security / JWT / AES

Var	Default	Notes
JWT_SECRET	—	Must be ≥ 32 chars in prod.
JWT_ALGORITHM	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	30
REFRESH_TOKEN_EXPIRE_DAYS	7
API_KEY_MASTER_KEY	—	base64 → 32-byte AES key. Encrypts BYOK keys + TOTP secrets.
CORS_ORIGINS	http://localhost:3000,http://127.0.0.1:3000	Irrelevant behind the single-origin proxy.

Payments & email

Var	Default	Notes
PAYMENT_PROVIDER	mock	Only mock implemented.
EMAIL_PROVIDER	console	resend in prod; console logs the link (self-host).
RESEND_API_KEY	(empty)	Required when EMAIL_PROVIDER=resend.
EMAIL_FROM	Maestro <noreply@maestro.example.com>
SITE_URL	http://localhost:3000	Backend's own copy for building email links (separate from the frontend's).
EMAIL_VERIFICATION_REQUIRED	true	Soft gate on POST /tasks + POST /api-keys.

Local model & embeddings

Var	Default	Notes
FREE_MODEL_ENDPOINT	http://localhost:11434/v1	Ollama OpenAI-compatible endpoint.
FREE_MODEL_NAME	qwen3.5:9b
OLLAMA_CHAT_ENABLED	false (prod)	Hosted Ollama serves embeddings only unless enabled.
EMBEDDING_ENDPOINT	(empty)	Falls back to FREE_MODEL_ENDPOINT.
EMBEDDING_MODEL_NAME	nomic-embed-text
EMBEDDING_DIM	768
GEMINI_MODEL_NAME	gemini-flash-latest

Agent tools

Var	Default	Notes
WEB_SEARCH_ENABLED	true
WEB_SEARCH_MAX_RESULTS	5
WEB_SEARCH_TIMEOUT_SECONDS	10
WEB_SEARCH_MAX_USES_PER_SUBTASK	2	(README says 3 — stale.)
DATA_FETCH_ENABLED	true
DATA_FETCH_TIMEOUT_SECONDS	—
DATA_FETCH_MAX_USES_PER_SUBTASK	—
CODE_EXECUTION_ENABLED	false	Enabling requires the Docker socket = host-takeover risk.
CODE_EXECUTION_IMAGE	python:3.12-slim
CODE_EXECUTION_TIMEOUT_SECONDS / _MEMORY_LIMIT / _CPUS / _MAX_USES_PER_SUBTASK	512m mem, etc.

Agent limits & LLM HTTP

Var	Default	Notes
MAX_ITERATIONS	10
MAX_REVIEW_ITERATIONS	3
TASK_TIMEOUT_SECONDS	1800
TASK_RETENTION_DAYS	30
SUBAGENT_MAX_PARALLEL	3
SUBAGENT_MAX_TOOL_CALLS	6
REVIEWER_FAIL_MODE	warn	warn | approve | reject.
LLM_REQUEST_TIMEOUT_SECONDS	180
LLM_CONNECT_TIMEOUT_SECONDS	10
LLM_SSRF_GUARD_ENABLED	true
OLLAMA_NATIVE_TOOLS	—	Enables native tool-calling for Ollama.

Frontend environment

Read server-side at request time (image stays domain-agnostic):

Var	Notes
SITE_URL	Canonical/OG/sitemap origin (server-only, not NEXT_PUBLIC_).
INTERNAL_API_ORIGIN	Server-side base for SSR fetches (http://backend:8000).
BACKEND_ORIGIN	Enables the /api/* rewrite when the frontend runs elsewhere.
NEXT_PUBLIC_WS_BASE_URL	Overrides same-origin WS base (usually empty).
SENTRY_DSN / SENTRY_ENVIRONMENT	Frontend Sentry (separate project from backend).
UMAMI_WEBSITE_ID	Self-hosted analytics id (optional).

Production differences (.env.prod.example)

Adds LOG_FORMAT=json, FRONTEND_SENTRY_DSN, DOMAIN, IMAGE_TAG, a secrets block (POSTGRES_PASSWORD, MONGO_USER/MONGO_PASSWORD, QDRANT_API_KEY, REDIS_PASSWORD), compose-network URLs, OLLAMA_CHAT_ENABLED=false, EMAIL_PROVIDER=resend, CODE_EXECUTION_ENABLED=false, and analytics vars (COMPOSE_PROFILES, UMAMI_*). See Deployment.