Configuration
Environment variables for self-hosted Engrammic deployments
This page covers self-hosted deployments only. For the full setup walkthrough, see the self-hosting guide.
The service is configured through environment variables. Create a .env file alongside your docker-compose.yml and reference it with env_file. The compose file that ships with the installer pre-sets infra hostnames and a few defaults; only override what you need to change.
Required
| Variable | Default | Purpose |
|---|---|---|
ENGRAMMIC_LICENSE_KEY | (none) | Your license key. Format: ENGR_... |
POSTGRES_PASSWORD | engrammic | Postgres password. Change this for any production deployment. |
EMBEDDING_MODEL | vertex_ai/text-embedding-005 | LiteLLM embedding model string. Routes by prefix. Example: openai/text-embedding-3-small. |
EMBEDDING_DIMENSIONS | 768 | Integer. Must match the model exactly. nomic and vertex-005 use 768; MiniLM uses 384. Changing this after data exists requires recreating Qdrant collections and re-embedding all stored data. |
Embedding Providers
Set the credentials for whichever provider you chose in EMBEDDING_MODEL. You only need one set.
| Provider | Variables |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Azure OpenAI | AZURE_API_KEY, AZURE_API_BASE |
| AWS Bedrock | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME |
| Google Vertex AI | VERTEX_PROJECT, VERTEX_LOCATION (requires gcloud credentials mount, already present in the selfhosted compose) |
| Ollama (local) | OLLAMA_API_BASE (example: http://host.docker.internal:11434) |
For a full list of supported embedding models, see the LiteLLM embedding docs. For running local models, see the local models guide.
Generation LLM
The generation LLM powers SAGE synthesis (deduplication, insight generation, contradiction detection). Without a usable LLM, SAGE runs in passive mode: storage and recall still work, synthesis is disabled.
Unlike embeddings, the LLM provider and model are not set by a single environment variable. They come from models.yaml, whose default tier uses Google Vertex (Gemini). To change the provider, override models.yaml (see Config Files); the environment only supplies credentials for whichever provider that file selects.
| Variable | Default | Purpose |
|---|---|---|
ANTHROPIC_API_KEY | (none) | Credentials when models.yaml selects the anthropic provider. |
OPENAI_API_KEY | (none) | Credentials when models.yaml selects the openai provider. Also used for OpenAI embeddings if chosen. |
GEMINI_API_KEY | (none) | Credentials when models.yaml selects the gemini provider. |
VERTEX_PROJECT / VERTEX_LOCATION | (none) | Project and region for the vertex provider (the default). Uses the mounted gcloud credentials, no API key. |
OLLAMA_BASE_URL | http://localhost:11434 | Endpoint when models.yaml selects the ollama provider. Note: separate from OLLAMA_API_BASE, which is for embeddings only. |
To switch the LLM (for example to OpenAI or a local Ollama model), edit the active tier's reasoning, fast, and query_expander entries in models.yaml and set the matching credential above. See Config Files for how to override models.yaml, and Running Models Locally for the Ollama walkthrough.
Infrastructure Connections
The selfhosted compose pre-sets these to match the service names. Override only if you are connecting to external instances.
Memgraph
| Variable | Default | Purpose |
|---|---|---|
MEMGRAPH_HOST | memgraph | Hostname |
MEMGRAPH_PORT | 7687 | Bolt port |
MEMGRAPH_USER | (empty) | Username |
MEMGRAPH_PASSWORD | (empty) | Password |
MEMGRAPH_POOL_SIZE | 50 | Connection pool size |
MEMGRAPH_POOL_TIMEOUT | 30.0 | Pool checkout timeout in seconds |
Qdrant
| Variable | Default | Purpose |
|---|---|---|
QDRANT_HOST | qdrant | Hostname |
QDRANT_PORT | 6333 | HTTP port |
QDRANT_GRPC_PORT | 6334 | gRPC port |
QDRANT_API_KEY | (none) | API key for secured Qdrant instances |
Redis
| Variable | Default | Purpose |
|---|---|---|
REDIS_HOST | redis | Hostname |
REDIS_PORT | 6379 | Port |
REDIS_PASSWORD | (none) | Password |
REDIS_DB | 0 | Database index |
REDIS_MAX_CONNECTIONS | 50 | Connection pool size |
Postgres
| Variable | Default | Purpose |
|---|---|---|
POSTGRES_HOST | postgres | Hostname |
POSTGRES_PORT | 5432 | Port |
POSTGRES_USER | engrammic | Username |
POSTGRES_DATABASE | engrammic | Database name |
POSTGRES_PASSWORD | engrammic | Password (also listed under Required) |
Server and Application
| Variable | Default | Purpose |
|---|---|---|
ENVIRONMENT | development | The selfhosted compose sets this to self-hosted. |
HOST | 127.0.0.1 | Bind address |
PORT | 8000 | Listen port |
WORKERS | 4 | Uvicorn worker count |
REQUEST_TIMEOUT | 30 | Request timeout in seconds |
LOG_LEVEL | INFO | Log verbosity. One of: DEBUG, INFO, WARNING, ERROR. |
DEBUG | false | Enables debug mode. Do not enable in production. |
RUN_MIGRATIONS | true | Migrations run automatically on startup. Set to false to disable. |
Telemetry
| Variable | Default | Purpose |
|---|---|---|
TELEMETRY__ENABLED | true | Anonymous aggregate usage statistics. Set to false to opt out. |
Note the double-underscore in TELEMETRY__ENABLED. Nested settings throughout the service use __ as a section delimiter (for example, SECTION__FIELD maps to section.field in config). The examples in Advanced Tuning below follow the same pattern.
Advanced Tuning
Most self-hosters never need to touch these. The service ships with sensible defaults for all internal settings, and the three examples below are the most commonly adjusted.
| Variable | Default | Purpose |
|---|---|---|
CUSTODIAN__ENABLED | false | Background contradiction and supersession detection. Increases write load. |
RERANKING__ENABLED | true | Cross-encoder reranking of recall results. Disable to reduce latency at the cost of recall quality. |
WEAK_LINKS__ENABLED | true | Speculative related-to edges created during ingestion. Disable to reduce graph size. |
The service exposes many more tuning flags mapped to internal settings. They all default to sensible values. Changing them is rarely needed and not covered here; reach out to founders@engrammic.ai if you have a specific tuning requirement.
Not Configurable by Self-Hosters
The following belong to the managed cloud service and are not applicable to self-hosted deployments:
- WorkOS auth (
WORKOS_*): Authentication for the hosted multi-tenant service. - Stripe billing: Subscription and payment processing.
- Rate-limit tiers: Per-plan request limits enforced by the managed gateway.
- Telemetry beacon secrets: Credentials for the hosted telemetry backend.
Never commit secrets to version control. Keep your .env file out of git (add it to .gitignore), or use a secrets manager to inject values at runtime.
Container Image
The production image is:
europe-north1-docker.pkg.dev/engrammic/releases/engrammic-api:latestContact founders@engrammic.ai to get registry access.