Configuration
The agent service is configured entirely through the environment. Required values have no built-in defaults: if one is missing, startup aborts and names the variable.
Validation happens once at startup, and completely. A misconfigured variable should not kill the service hours later on the first call that happens to need it.
Required
| Variable | Meaning |
|---|---|
| DATABASE_URL | PostgreSQL connection string (postgres:// or postgresql://). |
| KEYCLOAK_URL | Keycloak base URL without a trailing slash — the internal one, used for JWKS and token exchange. |
| KEYCLOAK_REALM | Name of the realm. |
| AGENT_CLIENT_ID | The service's OIDC client id; also the expected audience of incoming tokens. |
| AGENT_CLIENT_SECRET | The matching secret (confidential client). |
| PLATFORM_ENCRYPTION_KEY | Key material for the credential store, produced by scripts/generate-secrets.sh. |
| PORT | TCP port the HTTP server listens on. |
Rotate PLATFORM_ENCRYPTION_KEY only deliberately
The key for every stored secret is derived from this material. After a change, those secrets have to be entered again.
Identity and addresses
| Variable | Meaning |
|---|---|
| KEYCLOAK_ISSUER_URL | The public, browser-facing Keycloak address. It alone determines the expected token issuer. Unset, it falls back to KEYCLOAK_URL — correct for single-host and development setups, wrong as soon as inside and outside differ. |
| TRINO_URL | Address of the Trino coordinator. Defaults to the in-cluster service address. |
| MINIO_ENDPOINT, MINIO_REGION | Object storage for table data and the audit archive. |
Security
| Variable | Default | Meaning |
|---|---|---|
| SOURCE_TLS_MODE | verify | Transport security to source databases: verify enforces TLS with certificate verification, require TLS without it, disable none at all. Overridable per source. |
| SOURCE_EGRESS_ALLOWLIST | empty | Comma-separated host patterns or CIDRs. Set: outbound admin calls may only go there. Empty: permissive — except for the always-active block on link-local and cloud-metadata addresses. A malformed CIDR entry prevents startup. |
| TRINO_ACCESS_RULES_FILE | unset | Path the agent writes the generated row and column rules to — on a volume Trino also reads. Unset, policies are stored but not enforced. |
Embeddings
| Variable | Meaning |
|---|---|
| EMBEDDING_BASE_URL | OpenAI-compatible address of the embedding provider. The local model by default. |
| EMBEDDING_MODEL | Model name, nomic-embed-text by default. |
| EMBEDDING_API_KEY | Only needed if the provider requires one — the local model does not. |
| EMBEDDING_DIMENSIONS | Dimension of the vector column. Must match the migration; changing it means rebuilding the index. |
Audit archival
| Variable | Meaning |
|---|---|
| AUDIT_BUCKET | Bucket holding the archived hash chain, under Object Lock. |
| AUDIT_BATCH_SIZE, AUDIT_FLUSH_INTERVAL_MS | How large a batch grows and how long it may wait at most. |
| AUDIT_RETENTION_DAYS | Retention period in the archive. |
| AUDIT_S3_DISABLED | Turns archival off. For tests — not for production. |
Further switches
| Variable | Meaning |
|---|---|
| KEYCLOAK_ADMIN_USER, KEYCLOAK_ADMIN_PASSWORD | Effective only together. Without them the user and role management routes are not registered — the feature is simply absent. |
| CRAWL_ROOTS | The directories the fileshare crawler may touch at all. |
| MODEL_ANTHROPIC, MODEL_OPENAI, MODEL_OPENAI_COMPATIBLE, MODEL_CLAUDE_SUBSCRIPTION | Default model ids per provider, overridable per deployment. |
| CLAUDE_OAUTH_CLIENT_ID | Public client id for the sign-in-with-Claude flow. |
| K8S_API_URL, K8S_API_TOKEN, K8S_NAMESPACE | Only for reaching the Kubernetes API from outside the cluster. In-cluster, the mounted ServiceAccount provides everything. |
Secrets are generated for you
up.sh and bootstrap.sh create a .env with random values on first run. That file stays out of version control.
Applies to: This page describes lavalake 0.16.0. Product and documentation live in separate repositories — when in doubt, what the console shows is authoritative.
Something missing?
If these pages do not answer your question, we will walk through the platform against your own case in half an hour.
Book a demo