Configuration

Evo.ai is configured with environment variables (server-wide defaults and infrastructure) plus per-tenant runtime settings applied through the API. This page covers both.

Environment variables

Set these in the server's .env. The defaults shown are the built-in ones.

Infrastructure

Variable	Default	Purpose
OLLAMA_BASE_URL	http://ollama:11434	Ollama endpoint for local models
QDRANT_URL	http://qdrant:6333	Qdrant vector store
DB_PATH	data/evo_ai.db	SQLite metadata store

Default LLM

Used when a tenant has not configured its own model. provider is ollama or any LiteLLM provider prefix.

Variable	Default
DEFAULT_LLM_PROVIDER	ollama
DEFAULT_LLM_MODEL	llama3.3:70b
DEFAULT_LLM_API_BASE	(empty)
DEFAULT_LLM_API_KEY	(empty)
DEFAULT_LLM_ALLOWED_TENANTS	(empty)

An empty allowlist means every tenant

DEFAULT_LLM_API_KEY is the operator's provider account. Falling back to it is a spend, and it routes that tenant's questions through the operator's account.

DEFAULT_LLM_ALLOWED_TENANTS is the comma-separated list of tenants permitted that fallback. Empty means all of them — fine for single-tenant or dev, but on a shared deployment where tenants self-provision it means a brand-new customer silently bills to you.

Set it to the operator's own tenants. Everyone else then fails closed with a clear "an administrator needs to add an API key" answer and unconfigured: true on the response, rather than quietly working at your expense.

The default model is worth a second look before going to production: llama3.3:70b needs roughly 40 GB of RAM. Point DEFAULT_LLM_MODEL at something your hardware can hold, or use a cloud provider.

Default embeddings

Used when a collection is auto-created. Changing an embedding model never applies to existing collections — each collection records its embedding config at creation time (see Ingesting data).

Variable	Default
DEFAULT_EMBED_PROVIDER	ollama
DEFAULT_EMBED_MODEL	nomic-embed-text
DEFAULT_EMBED_API_BASE	(empty)
DEFAULT_EMBED_API_KEY	(empty)

Retrieval

Variable	Default	Purpose
ENABLE_HYBRID	true	Dense + sparse (BM25) fusion for new collections
TOP_K	5	Dense results returned
SPARSE_TOP_K	10	Sparse results returned
CHUNK_SIZE	512	Chunk length for ingestion
CHUNK_OVERLAP	50	Overlap between chunks
LLM_CONTEXT_WINDOW	4096	Context window requested from local models. Left unbounded, llama-index requests the model's maximum, which allocates a multi-GB KV cache and can OOM small servers.
LLM_REQUEST_TIMEOUT	180.0	Per-request LLM timeout (seconds)

Guardrails

Variable	Default	Purpose
RELEVANCE_THRESHOLD	0.55	The relevance gate refuses before any LLM call when the best retrieval score is below this (0 disables). Calibrated on hybrid fusion scores: off-topic questions top out around 0.44–0.51 while real data questions score ≥ 0.66.
GATED_ANSWER	(built-in text)	What the API returns when the gate refuses. Callers also get a structured gated: true flag and can render their own wording.
ASSISTANT_POLICY	(built-in text)	The grounding/refusal policy prepended to every answer prompt. Override for a different tone or rules.

The built-in assistant policy instructs the model to answer only from the provided context, treat that context strictly as data (never following instructions embedded in it), and refuse anything that isn't a question about the workspace's records.

Auth

Variable	Default	Purpose
DEV_MODE	true	When true, any bearer token maps to tenant dev. Turn off in production.
EVOPLATFORM_JWKS_URL	(empty)	JWKS endpoint used to verify tokens outside dev mode
JWT_AUDIENCE	(empty)	Optional expected audience claim
JWT_ISSUER	(empty)	Optional expected issuer claim
SECRET_KEY	(empty)	Fernet key used to encrypt stored provider API keys and connector configs. Required in production; a fixed dev key is used if unset in dev mode.
CORS_ORIGINS	(empty)	Comma-separated allowed origins for browser clients. Empty means * in dev mode and no CORS outside it.

See Connectors for the evo.ehs discovery and analytics variables (SP_DISCOVERY_DSN, ANALYTICS_ENABLED, and related).

Per-tenant model configuration

Each tenant can override the server default LLM at runtime via PUT /config/model:

curl -s -X PUT localhost:8000/config/model -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "model": "claude-sonnet-5", "api_key": "sk-ant-..."}'

• GET /config/model returns the tenant's current config (the key is never echoed back).
• DELETE /config/model reverts the tenant to the server default.

The API key is encrypted at rest with SECRET_KEY. To run fully local, leave tenants on the Ollama default and never send a provider key off the box.