> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/deployment-and-infrastructure/configuration-reference.md). # Configuration Reference Every `eddi.*` property EDDI reads, with its default and the environment variable that sets it. This is the deployment/operator surface — **agent behaviour is configured as JSON documents, not here**. If you are trying to change what an agent *says or does*, you want [Behavior Rules](/agent-configuration/behavior-rules.md), [LLM Integration](/agent-configuration/langchain.md) or [Properties](/architecture-and-concepts/properties.md) instead. *** ## How to set these Three interchangeable mechanisms, in ascending order of precedence: | Where | Form | Use it for | | ------------------------------------------- | ----------------------------------- | --------------------------------------------- | | `src/main/resources/application.properties` | `eddi.schedule.poll-interval=15s` | Source builds and the shipped defaults | | Environment variable | `EDDI_SCHEDULE_POLL_INTERVAL=15s` | Docker, Compose, Kubernetes — the normal path | | JVM system property | `-Deddi.schedule.poll-interval=15s` | One-off local overrides | **The environment-variable spelling is mechanical:** uppercase the property name and replace **every character that is not a letter or a digit** with `_`. Both `.` and `-` are replaced — neither is dropped. ``` eddi.schedule.poll-interval → EDDI_SCHEDULE_POLL_INTERVAL eddi.vault.master-key → EDDI_VAULT_MASTER_KEY eddi.openai-compat.api-key → EDDI_OPENAI_COMPAT_API_KEY eddi.tools.websearch.google.api-key → EDDI_TOOLS_WEBSEARCH_GOOGLE_API_KEY ``` > **Getting this wrong fails silently.** An unrecognised environment variable is not an error — the property simply keeps its default and the service starts normally. `EDDI_VAULT_MASTERKEY` (dash deleted rather than replaced) leaves `eddi.vault.master-key` empty, which means the vault is inactive, and a `scope: "secret"` property setter then fails the whole turn. Nothing in the startup log mentions the variable you set. > > To check what actually bound, read the value back from the Dev UI at `/q/dev`, or compare against the spellings already used in `docker-compose.yml`, `.env.example` and `k8s/`. Quarkus profiles prefix the key: `%dev.eddi.usermemories.deleteOlderThanDays=-1` applies in dev mode only. > **Empty is not the same as unset.** Several properties ship deliberately empty (`eddi.vault.master-key`, `eddi.deployment.env`). An empty value is a real value that disables or defaults the feature; it is not an error, and startup will not complain. *** ## Data store & messaging | Property | Default | Description | | ------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.datastore.type` | `mongodb` | `mongodb` or `postgres`, matched exactly and case-sensitively — any other value, `Postgres` included, means MongoDB. Selects which store implementations EDDI uses, but not the connection: PostgreSQL also needs the `postgres` Quarkus profile (`QUARKUS_PROFILE=postgres`, which activates the datasource and sets this property for you) and `QUARKUS_DATASOURCE_JDBC_URL`, `QUARKUS_DATASOURCE_USERNAME` and `QUARKUS_DATASOURCE_PASSWORD`. Setting `EDDI_DATASTORE_TYPE=postgres` without the profile leaves the datasource inactive. A PostgreSQL deployment never opens a MongoDB connection, so no MongoDB is needed — see [Architecture → DB-agnostic design](/architecture-and-concepts/architecture.md) | | `eddi.datastore.postgres.substring-search-index` | `true` | PostgreSQL only. Builds `pg_trgm` trigram indexes for the descriptor listings' search box, in the background after boot (`CREATE INDEX CONCURRENTLY`, so writes are not blocked). Needs `CREATE EXTENSION pg_trgm`, which is trusted since PostgreSQL 13; if the role is refused, a warning is logged and search runs unindexed. Costs about 0.1 ms more per descriptor write. `false` builds nothing | | `eddi.messaging.type` | `in-memory` | `in-memory` or `nats`. `in-memory` confines the conversation coordinator to a single instance; `nats` distributes it | ### NATS JetStream (only when `eddi.messaging.type=nats`) | Property | Default | Description | | ----------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.nats.url` | `nats://localhost:4222` | Server URL | | `eddi.nats.stream-name` | `EDDI_CONVERSATIONS` | JetStream stream carrying conversation work | | `eddi.nats.dead-letter-stream-name` | `EDDI_DEAD_LETTERS` | Stream that receives messages past `max-retries` | | `eddi.nats.max-retries` | `3` | Redelivery attempts before dead-lettering | | `eddi.nats.ack-wait-seconds` | `60` | How long JetStream waits for an ack before redelivering. Must exceed your slowest conversation turn, or slow turns are processed twice | | `eddi.nats.stream-max-age` | `1h` | Age bound of the conversation stream. Its messages are ordering markers nothing consumes, so the oldest are discarded when any of the three bounds is reached | | `eddi.nats.stream-max-messages` | `100000` | Message-count bound of the conversation stream | | `eddi.nats.stream-max-bytes` | `268435456` | Size bound of the conversation stream (256 MiB) | *** ## Conversation lifecycle & retention | Property | Default | Description | | -------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.conversations.maximumLifeTimeOfIdleConversationsInDays` | `90` | Idle conversations are ended after this many days without a turn. A daily sweep does it, first run five minutes after boot; it only changes the state to `ENDED` and deletes nothing, and a conversation paused for human approval is never ended. **`-1` (or `0`) disables it**: no conversation is ended for idleness, and startup logs that it is off. The same sweep still undeploys an old agent version once no conversation on it is active, whatever this is set to | | `eddi.conversations.deleteEndedConversationsOnceOlderThanDays` | `365` | Ended conversations are permanently deleted after this many days since their last interaction. Soft-deleted conversations (deleted without `deletePermanently`) are ended and follow the same clock | | `eddi.conversations.max-input-chars` | `200000` | Longest turn input, in characters, a caller may send to an existing conversation. Longer input is refused before anything reaches the model: **413** `input_too_large` on the REST and streaming conversation endpoints, **400** `input_too_large` on the OpenAI-compatible API, invalid params over A2A; other surfaces built on those entry points report the refusal as an error. `0` or negative disables the limit. Turns the engine drives itself for group members and sub-agents are exempt | | `eddi.usermemories.deleteOlderThanDays` | `-1` | Persistent user memories older than this are deleted. **`-1` disables the sweep** — memories are kept forever until you set a positive number. Relevant to [GDPR](/security-and-compliance/gdpr-compliance.md) and [HIPAA](/security-and-compliance/hipaa-compliance.md) | | `eddi.conversation.client-context.permitted-reserved-keys` | *(empty)* | Comma-separated engine-reserved context keys that clients are allowed to set. Empty (the default) drops all of them from client-supplied context. Only `groupId`, `groupConversationId`, `groupDepth`, `groupTranscript`, `dynamicAgentConfig`, `dynamicCreatedAgentIds` and `delegationDepth` are recognized; anything else is ignored. Set this only where every caller is trusted — see [Passing Context Information](/agent-configuration/passing-context-information.md#reserved-context-keys) | | `eddi.coordinator.max-active-conversations` | `10000` | Ceiling on concurrently tracked conversations | | `eddi.coordinator.max-dead-letters` | `1000` | Retained dead-letter entries. `-1` unbounded, `0` retain none | ### Graceful shutdown Tuned for Kubernetes rolling updates: EDDI reports itself not-ready first, waits for the load balancer to notice, then drains in-flight conversations. | Property | Default | Description | | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.shutdown.readiness-grace-seconds` | `3` | Time between failing readiness and starting the drain. Must exceed your ingress's health-check interval, or requests keep arriving mid-drain | | `eddi.shutdown.drain-timeout-seconds` | `20` | How long to wait for in-flight conversations before exiting anyway. Keep it below your orchestrator's `terminationGracePeriodSeconds` | | `eddi.shutdown.drain-poll-millis` | `100` | How often the drain re-checks for completion | ### Streaming | Property | Default | Description | | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.streaming.cancel-on-client-disconnect` | `true` | Abort the turn when an SSE client goes away. Set `false` to let the turn finish and persist, so a reconnecting client can read the result | | `eddi.llm.tool-loop.streaming.enabled` | `true` | Stream tokens during tool-calling turns rather than falling back to a single chunk | *** ## Scheduling Full narrative and metrics: [scheduling.md → Deployment Configuration](/conversations-and-orchestration/scheduling.md#deployment-configuration). | Property | Default | Description | | ------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.schedule.enabled` | `true` | Master switch for the poller | | `eddi.schedule.poll-interval` | `15s` | How often due schedules are looked for — the floor on firing punctuality | | `eddi.schedule.poll-batch-size` | `100` | Schedules claimed per cycle | | `eddi.schedule.lease-timeout` | `10m` | Claim lease before another instance may re-claim. Must outlast `fire-timeout` + 30 s, or a running fire becomes reclaimable and executes twice; a shorter value is raised at startup (to `fire-timeout + 30s + 1m`) with a warning | | `eddi.schedule.max-retries` | `5` | Attempts before `DEAD_LETTERED` | | `eddi.schedule.backoff-base-seconds` | `15` | Retry delay = `base × multiplier^(attempt-1)` | | `eddi.schedule.backoff-multiplier` | `4` | Defaults give 15s, 60s, 4m, 16m, 64m | | `eddi.schedule.min-interval-seconds` | `60` | Smallest cron interval a schedule may request | | `eddi.schedule.instance-id` | *(hostname)* | Cluster claim identity. Set explicitly where hostnames are recycled | | `eddi.schedule.default-timezone` | `UTC` | IANA zone for schedules that name none | | `eddi.schedule.fire-timeout` | `5m` | How long one fire (conversation turn, Dream run, team cadence) may run before it is interrupted and recorded FAILED ("exceeded eddi.schedule.fire-timeout"). Raise it for long Dream runs; the lease follows | | `eddi.schedule.hitl-timeout-retry-interval` | `2m` | When a HITL approval timeout's decision cannot be applied yet (store blip, node draining, a decision in flight), when it is tried again. HITL timeouts are re-armed, never dead-lettered | | `eddi.schedule.persistent-conversation-max-steps` | `0` | Off by default. Steps after which a `conversationStrategy: persistent` schedule ends its (idle) conversation and starts a new one, carrying over its `conversation`-scoped properties but not the LLM history. Keeps the document clear of MongoDB's 16 MB limit; see [Scheduling](/conversations-and-orchestration/scheduling.md#long-running-persistent-schedules) | | `eddi.schedule.fire-log-retention` | `90d` | Fire logs older than this are deleted by a periodic sweep. `0` keeps everything — a 60-second heartbeat alone writes \~525,600 rows a year | | `eddi.schedule.fire-log-prune-interval` | `1h` | How often that sweep runs. The `DELETE` is by timestamp and therefore idempotent, so it needs no cluster claim | | `eddi.rag.ingestion.schedule-repair.enabled` | `true` | At startup, gives a next fire time to any RAG ingestion schedule stored without one. Such a row reads back enabled and can never be selected by the poller, so it looks scheduled and never runs. The sweep only touches rows that have no fire time at all, so an already armed row is skipped and a boot with nothing left to repair does no writes. It is not guaranteed to finish in one pass: it stops at its own 20,000-row bound, and at a store failure, logging a warning that says which — a later boot picks up the rows it never examined — see [rag.md](/agent-configuration/rag.md#ingestion-sources) | *** ## Security & authentication > Authentication itself is Quarkus OIDC, not an `eddi.*` property: `quarkus.oidc.tenant-enabled` (default `false`) is the master switch, and `authorization.enabled` tracks it so `@RolesAllowed` is enforced exactly when OIDC is on. See [security.md](/security-and-compliance/security.md). | Property | Default | Description | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi.security.allow-unauthenticated` | `false` | Permits running with OIDC disabled outside dev. `AuthStartupGuard` refuses a production boot without it | | `eddi.security.ssrf-protection.enabled` | `false` | **Opt-in.** Validates the fully resolved target of httpCalls, MCP and A2A calls and stops following redirects. Off by default because configured targets legitimately reach internal hosts — **turn it on if any outbound URL is influenced by conversation input.** The cloud instance-metadata service (and the link-local range it lives in) is refused regardless of this setting. See [security.md → SSRF Protection](/security-and-compliance/security.md#ssrf-protection--urlvalidationutils) | | `eddi.mcp.allow-unauthenticated` | `false` | Exposes the MCP server without auth. Needs its own opt-in on top of `eddi.security.allow-unauthenticated` — inheriting one flag must not be enough to open agent CRUD | | `eddi.secretstore.allow-unauthenticated` | `false` | Same, for the secrets vault REST surface | | `eddi.caller-identity.enabled` | `true` | Enables `${caller:token}` / `${caller:userId}` in httpCall headers. See [httpcalls.md](/agent-configuration/httpcalls.md) | | `eddi.caller-identity.self-release.enabled` | `true` | Also releases `${caller:token}` to this deployment's own address (`eddi.self.base-url`), not only to the caller's origin — how the Platform Operator's tools call EDDI as the chatting user. The self address bypasses any reverse proxy in front of EDDI, so set `false` if that proxy enforces restrictions EDDI's own authorization does not. See [httpcalls.md](/agent-configuration/httpcalls.md) | | `eddi.self.base-url` | *(derived: `http://${quarkus.http.host}:${quarkus.http.port}` when `quarkus.http.host` names one specific address, loopback ones such as `127.0.0.5` or `::1` included, an IPv6 literal bracketed as `http://[::1]:7070`; `http://127.0.0.1:${quarkus.http.port}` for a wildcard, empty or `localhost` bind)* | The address EDDI can reach **itself** at — what the Platform Operator's generated tools target. A bare `scheme://host[:port]`; a path, query, fragment or credentials make it ignored. Set it only when loopback is wrong (TLS terminated in-process, a mesh-required service name) or when SSRF protection is on — the value must then pass the full SSRF target policy. Required with `quarkus.http.port=0`, where nothing can be derived. Served at `GET /administration/operator/self-url` | | `eddi.keycloak.public.url` | *(empty)* | Browser-facing Keycloak URL when it differs from the in-cluster one | | `eddi.http.limits.default-max-body-size` | `25M` | Largest request body any endpoint accepts, **except** a knowledge base's file upload (`POST /ragstore/rags/{id}/sources/{sourceId}/files`, matched below `quarkus.http.root-path`), which keeps `quarkus.http.limits.max-body-size` (60 MB). Raised automatically to what an attachment at `eddi.attachments.max-size-bytes` takes base64-encoded in a JSON body (4/3 plus 1 MB — about 27.7 MB for the default 20 MB), so raising the attachment limit never leaves inline attachments refused here — up to `quarkus.http.limits.max-body-size`, which refuses a larger request before any endpoint sees it. An attachment limit above about 44 MB needs more than the 60 MB ceiling once base64-encoded: raise `quarkus.http.limits.max-body-size` with it (a 60 MiB attachment needs `82M`). EDDI logs a WARN at startup naming both settings and the ceiling needed when they disagree. A ZIP import is held to it too: raise it to import a larger archive. Judged on the declared `Content-Length` before the body is read; refusals close the connection. See [rag.md](/agent-configuration/rag.md#ingestion-sources) | | `eddi.http.limits.refuse-unsized-bodies` | `true` | Refuses, with 411, a chunked HTTP/1.1 request body — one sent without a `Content-Length` — on every endpoint but the file upload. Such a body cannot be measured before it is read, and counting it as it arrives is not possible where the limit is enforced. JSON clients and browsers send the length; set `false` only for a client that cannot, which leaves those bodies bounded by the global 60 MB alone. An HTTP/2 request without a `content-length` is always left to that global ceiling: at the point the limit is enforced it cannot be told apart from a request with no body | | `eddi.metrics.http-policy` | `eddi-metrics-reader` | Quarkus HTTP policy for `/q/metrics`. The default admits a token carrying one of `eddi.metrics.roles-allowed`; with OIDC on, an anonymous scrape gets 401 and a token without the role 403. `authenticated` admits any token (the 6.5 default); `permit` opens this one path — only where it cannot be reached from outside. See [monitoring-guide.md → Scraping with authentication on](/deployment-and-infrastructure/monitoring-guide.md#scraping-with-authentication-on) | | `eddi.metrics.roles-allowed` | `eddi-admin,eddi-metrics` | The realm roles the default metrics policy admits. `eddi-metrics` is not in the shipped realm: create it and give it to the scrape's service account | | `eddi.api-docs.http-policy` | `eddi-api-docs-reader` | Quarkus HTTP policy for the API description — `/openapi`, `/q/openapi`, `/q/swagger-ui`. The default admits a token carrying one of `eddi.api-docs.roles-allowed`; `authenticated` admits any token, `permit` anyone. See [security.md → Deny by default](/security-and-compliance/security.md#deny-by-default-and-what-a-role-less-token-reaches) | | `eddi.api-docs.roles-allowed` | `eddi-admin,eddi-editor,eddi-user,eddi-approver,eddi-viewer` | The realm roles the default API-description policy admits — any EDDI role. The Manager reads `/openapi` for the backend version, and the Platform Operator for its tool list | | `eddi.chat.frame-ancestors` | `'none'` | CSP `frame-ancestors` for the Chat UI at `/chat` — the origins allowed to embed it in an `