Skip to content
Engram Docs

Environment Variables

Required

Section titled “Required”
VarWhat it does
ENGRAM_PUBLIC_URLThe HTTPS URL where users reach Engram. Used for OAuth redirects, MCP discovery, email links.
SECRET_KEY_BASEPhoenix cookie/session signing. Generate with openssl rand -base64 48.
ENCRYPTION_MASTER_KEYWraps per-user DEKs. Losing this = data loss. 32+ bytes base64. Full encryption-related env reference under Encryption below.
DATABASE_URLPostgres connection string.
STORAGE_BACKENDs3 (the only supported value as of v0.5.19 / PR #62; the legacy database BYTEA adapter has been removed). Default s3.

Embedding provider

Section titled “Embedding provider”
VarWhat it does
EMBED_BACKENDollama or voyage. Default voyage (set to ollama for self-host without a Voyage account).
EMBED_MODELOverride the default model. For Ollama, defaults to nomic-embed-text (768 dims).
EMBED_DIMSOverride the embedding dimension count. Match your model.
VOYAGE_API_KEYRequired when EMBED_BACKEND=voyage. Get one from voyageai.com.
DOC_EMBED_MODEL / QUERY_EMBED_MODELOptional asymmetric retrieval — different models for documents vs queries (Voyage-specific).

Storage (when STORAGE_BACKEND=s3)

Section titled “Storage (when STORAGE_BACKEND=s3)”
VarWhat it does
STORAGE_ENDPOINTS3 endpoint URL. http://minio:9000 for default MinIO.
STORAGE_REGIONS3 region. Required for AWS, ignored by MinIO.
STORAGE_BUCKETBucket name for attachments.
STORAGE_ACCESS_KEY_IDS3 access key.
STORAGE_SECRET_ACCESS_KEYS3 secret.

Qdrant

Section titled “Qdrant”
VarWhat it does
QDRANT_URLQdrant HTTP endpoint. Default: http://qdrant:6333.
QDRANT_API_KEYAPI key if Qdrant has auth on.

Limits

Section titled “Limits”
VarDefaultWhat it does
MAX_NOTE_SIZE_BYTES1048576 (1 MiB)Per-note size cap
MAX_ATTACHMENT_SIZE_BYTES26214400 (25 MiB)Per-attachment size cap
RATE_LIMIT_PER_MINUTE600Per-user request limit

Auth (self-host)

Section titled “Auth (self-host)”
VarWhat it does
AUTH_PROVIDERlocal for self-host. (Cloud uses clerk.)
OAUTH_ALLOWED_REDIRECT_HOSTSComma-separated list of redirect hostnames allowed during MCP OAuth.

Observability

Section titled “Observability”
VarWhat it does
LOG_LEVELinfo, warn, error. Default info.
SENTRY_DSNIf set, errors stream to Sentry.
PROMEX_ENABLEDtrue to expose /metrics for Prometheus scrape.

Encryption

Section titled “Encryption”

ENCRYPTION_MASTER_KEY is listed under Required above — the rest of the encryption-related env lives here.

VarWhat it does
ENCRYPTION_MASTER_KEY_PREVIOUSRescue lane during master-key rotation. Unset after rotation completes.
ENCRYPTION_MASTER_KEY_VERSIONDefault 1. Bump during rotation (see Encryption Setup).
DEK_CACHE_TTL_MSDEK cache TTL in ms. Default 3600000 (1 hour).
KEY_PROVIDERlocal (default) or aws_kms. AWS KMS provider is operator-only today; see backend repo.
BOOT_CANARY_ENABLEDfalse disables the boot canary check. Leave default unless you know why.

Phoenix host / scheme

Section titled “Phoenix host / scheme”
VarWhat it does
PHX_HOSTPublic hostname (e.g. engram.example.com). Used for URL generation.
PHX_SCHEMEhttps in prod, http in dev.
PHX_PORTDefault 443 in prod.
PHX_SERVERSet to enable the HTTP server in prod.exs releases.

Billing (cloud only)

Section titled “Billing (cloud only)”

PADDLE_API_KEY, PADDLE_NOTIFICATION_SECRET, PADDLE_CLIENT_TOKEN, PADDLE_STARTER_PRICE_ID, PADDLE_PRO_PRICE_ID, PADDLE_ENV — all unset on self-host. When PADDLE_API_KEY is missing the billing plumbing short-circuits cleanly (no onboarding gate, no subscription checks).