Configuration
The platform is configured entirely through environment variables. This page lists every variable actually read by the code, where it is read, and its default.
Backend variables
Read via python-dotenv (load_dotenv()) from backend/app/.env or the process environment.
| Variable | Default | Read in | Purpose |
|---|---|---|---|
OPENAI_API_KEY | (none — required) | services/openai_service.py, services/multi_agent_email_service.py, services/document_service.py | Auth for all chat, analysis, and embedding calls |
OPENAI_MODEL | gpt-4o-mini | same service modules + routers/agents.py (cost logging) | Chat/completion model for every LLM call |
OPENAI_EMBEDDING_MODEL | text-embedding-3-small | services/document_service.py | Embedding model for RAG ingestion and retrieval |
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-smallThe .env file holds a live API key. It is ignored by .gitignore; keep it that way. If a key leaks, revoke it at platform.openai.com immediately. See Security.
Behavior when OPENAI_API_KEY is missing
Each service guards explicitly:
if not os.getenv("OPENAI_API_KEY"):
raise ValueError("OPENAI_API_KEY is missing. Please add it to your .env file.")- Chat (
POST /agents/{id}/chat) — the router catches the exception, stores the fallback response "Sorry, I could not generate a response right now.", and records the run withstatus="failed"and the error inerror_message. The HTTP response is still200. - Email analysis / workflows / RAG — the exception propagates to the router's
exceptblock, a failedToolCallis logged, and the client receives500with the error detail.
Non-configurable backend values
These are currently hardcoded — changing them means editing source (tracked on the Roadmap):
| Value | Location | Hardcoded value |
|---|---|---|
| Database URL | database.py | sqlite:///./agentops.db |
| Chroma path | services/document_service.py | ./chroma_db |
| Chroma collection | services/document_service.py | agent_documents |
| Chunk size / overlap | services/document_service.py | 800 / 100 characters |
| Chat temperature | services/openai_service.py | 0.3 (chat), 0.2 (analysis/RAG), 0 (evaluator/reviewer) |
| Cost table | services/monitoring_service.py | gpt-4o-mini: $0.15 / $0.60 per 1M input/output tokens |
Both relative paths (./agentops.db, ./chroma_db) resolve against the working directory, which is why the backend must be started from backend/app/ — see Installation.
Frontend variables
Read from process.env in server-side code only (route handlers and server components). Set them in frontend/.env.local or the shell.
| Variable | Default | Read in | Purpose |
|---|---|---|---|
AGENTOPS_API_BASE_URL | http://localhost:8001 | app/api/agents/route.ts | Base URL the API proxy forwards to |
AGENTOPS_DASHBOARD_API_URL | http://localhost:8001/agents/1/dashboard | app/dashboard/page.tsx | Full URL the dashboard fetches |
AGENTOPS_AGENTS_API_URL | http://localhost:8001/agents/ | app/agents/page.tsx | Full URL the agents list fetches |
AGENTOPS_API_BASE_URL=http://localhost:9000
AGENTOPS_DASHBOARD_API_URL=http://localhost:9000/agents/1/dashboard
AGENTOPS_AGENTS_API_URL=http://localhost:9000/agents/AGENTOPS_DASHBOARD_API_URL embeds the agent ID in the URL. Point it at a different agent by changing the URL, or extend the dashboard page to take a dynamic ID — see Frontend Data Fetching and Known Issues.
Documentation site variables
None. mkdocs build needs no environment variables; Vercel deployment settings live in vercel.json — see Docs Deployment.
What does not exist (yet)
To keep expectations accurate: there is no configuration for authentication secrets, database pooling, Redis, task queues, CORS origins, or logging levels — because those subsystems do not exist yet. See the Roadmap.
Related pages
- Installation — where these files live
- Deployment — configuration in production
- Security — secret handling