Look up configuration settings
A setting only helps when the selected DVARA distribution reads it. Use this reference to find the exact key, its default, where it works, and whether changing it requires a restart.
This page covers self-managed runtime settings. Configure workspaces, routes, policies, credentials, budgets, MCP servers, and A2A agents in DVARA Flightdeck on the Enterprise platform. Managed-service billing settings are not part of the self-managed contract.
Which configuration source owns the change?
| Source | Use it for | When it applies |
|---|---|---|
Open Source gateway.yaml | Providers, workspaces, API-key fingerprints, routes, policies, output schemas, prompt templates, and local rate limits | Read once at startup; restart after a change |
| Environment variables or startup arguments | Ports, secrets, feature switches, global defaults, and process behavior | At process startup; restart after a change |
| Enterprise DVARA Flightdeck | Managed product configuration | About 10 seconds at the default settings, when the next signed bundle reaches each Gateway; no restart |
Enterprise bootstrap.yaml | Seed initial workspaces, API keys, and routes into Flightdeck's database | At Flightdeck startup; existing identities are skipped. From 1.8.2 a Gateway given a bootstrap file refuses to start. |
| Enterprise signed configuration bundle | Every Enterprise Gateway pod from 1.8.2; it is how Flightdeck's configuration reaches them | At the bundle poll interval; no restart |
The Open Source gateway.yaml and the Enterprise bootstrap.yaml are different schemas. Do not copy a block from one into the other. See the bootstrap mode table before setting a bootstrap variable.
How do environment variable names work?
Most application properties use the conventional uppercase spelling with punctuation replaced by underscores:
dvara.flightdeck.portal.enabled
→ DVARA_FLIGHTDECK_PORTAL_ENABLED
Use the explicit environment variable in the tables when one is listed. Several compatibility names do not follow the mechanical conversion.
The Enterprise Helm chart is the preferred source for Kubernetes values. Do not translate a Helm value into an environment variable unless the chart documents that mapping.
What can gateway.yaml contain?
The Open Source distribution reads ${NAME} and ${NAME:-fallback} placeholders from the environment. The fallback applies when the variable is unset or set but empty. Secrets should remain in environment variables.
| Section | Important fields | Required behavior |
|---|---|---|
providers[] | name, type, api_key, base_url, and provider-specific credential fields | type is required. Use api_key: ${PROVIDER_API_KEY} rather than a literal secret. |
workspaces[] | id, name, status, region, metadata, credentials | id is required. metadata holds per-workspace governance overrides. |
api_keys[] | key_hash, workspace, name, scopes | key_hash must be sha256: followed by 64 lowercase hexadecimal characters. Plaintext key and generate entries are refused. Every name must be unique across the file. |
routes[] | id, model, provider, strategy, providers, fallback, pinned_model_version | Use one provider or a provider list. Unsupported strategies are refused at startup. In 1.8, fallback is accepted but does not control the automatic resolver, and pinned_model_version does not change the request sent upstream. Do not rely on either field as a production routing control. |
policies[] | id, workspace, status, dsl | workspace is optional for a global policy. When set it must be declared under workspaces or named by an API key, otherwise startup is refused. The Open Source distribution applies ACTIVE policies. |
output_schemas[] | id, model or route, schema, enabled | At least one of model or route is required. |
prompt_templates[] | id, workspace, name, description, model, system, template, status, tags | Template variables are derived from {{name}} placeholders. |
rate_limits | requests_per_minute, tokens_per_minute, requests_burst, tokens_burst | Omit a burst value to use the matching rate as capacity. Counters are local to this process. |
The smallest useful file is shown in Configure DVARA safely. The Open Source distribution quickstart shows how to generate an API key and store only its fingerprint.
Which shared process settings are supported?
These settings are present in the Open Source distribution and Enterprise DVARA Gateway unless the availability cell says otherwise.
| Property | Environment variable | Default | Availability and effect |
|---|---|---|---|
server.port | SERVER_PORT | 8080 | Gateway HTTP port. Restart required. |
spring.servlet.multipart.max-file-size | DVARA_BATCH_MAX_FILE_SIZE | 100MB | Maximum /v1/files upload size. The same value also sets the request-size limit. |
dvara.id.node | DVARA_ID_NODE | derived | Identifier node from 0 through 1023. Set a unique value on every replica when stable StatefulSet ordinals are not available. |
dvara.audit.file.path | DVARA_AUDIT_FILE_PATH | blank | Open Source distribution only. A blank path drops audit events and logs a startup warning. Set a writable path and an HMAC secret together. |
dvara.audit.hmac-secret | DVARA_AUDIT_HMAC_SECRET | development placeholder | Signs the local or persistent audit chain. Replace the placeholder before relying on tamper evidence. |
dvara.encryption.master-password | DVARA_ENCRYPTION_MASTER_PASSWORD | blank | Decrypts ENC: values in the Open Source distribution and encrypted Enterprise credentials. Required when encrypted storage is used. |
dvara.audit.encrypt-stored-hmac-secret | — | removed/inert | Enterprise compatibility note. Final 1.8 does not generate or store a new HMAC secret. Supply one DVARA_AUDIT_HMAC_SECRET to every signer and verifier. A master password is read only to recover an encrypted row left by an earlier build. |
dvara.persistence.telemetry-retention.eval-results-days | — | 90 | Enterprise only. A value of 0 or less keeps these rows. |
dvara.persistence.telemetry-retention.prompt-experiment-events-days | — | 90 | Enterprise only. A value of 0 or less keeps these rows. |
dvara.persistence.telemetry-retention.shadow-policy-events-days | — | 90 | Enterprise only. A value of 0 or less keeps these rows. |
dvara.persistence.telemetry-retention.shadow-routing-events-days | — | 90 | Enterprise only. A value of 0 or less keeps these rows. |
dvara.persistence.telemetry-retention.batch-size | — | 5000 | Maximum rows removed per batch. |
dvara.persistence.telemetry-retention.cron | — | 0 20 4 * * * | Daily schedule. Set - to disable the sweep. |
dvara.actuator.api-key | DVARA_ACTUATOR_API_KEY | blank | Bearer for protected actuator endpoints. If blank, no bearer value can unlock those endpoints. |
dvara.actuator.metrics-api-key | DVARA_ACTUATOR_METRICS_API_KEY | blank | Separate bearer for /actuator/prometheus. Give it a different value from the operator key. |
dvara.region.id | DVARA_REGION_ID | blank | Identifies this Gateway region. A blank value makes the instance region-unaware. |
dvara.region.name | DVARA_REGION_NAME | blank | Human-readable region name. |
management.tracing.sampling.probability | TRACING_SAMPLING_PROBABILITY | 1.0 | Trace sample ratio from 0.0 to 1.0. Export still requires an OTLP endpoint. |
management.opentelemetry.tracing.export.otlp.endpoint | OTEL_EXPORTER_OTLP_ENDPOINT | unset | OTLP base URL. Do not append /v1/traces; the exporter adds the signal path. Unset means no OTLP export. |
Process properties take effect at startup. Restart after changing any row in this table.
New user-facing record IDs are 13-character, time-sortable identifiers. Existing UUIDs remain valid and are not rewritten. DVARA derives the identifier node from a StatefulSet ordinal when the hostname ends in -<number>; otherwise it hashes the pod name, or chooses a random node when no pod identity is available. For a multi-replica Deployment, assign a unique DVARA_ID_NODE from 0 through 1023 to each replica. Values outside that range wrap and can collide with another node, so do not use them.
How do you activate an LLM provider?
The provider registers only when its condition is satisfied at startup.
| Provider | Environment variable or condition | Default base URL |
|---|---|---|
| OpenAI | OPENAI_API_KEY | https://api.openai.com/v1 |
| Anthropic | ANTHROPIC_API_KEY | Provider default. From 1.8.5 dvara.llm-gateway.providers.anthropic.base-url sets another one, as for other providers |
| Gemini | GEMINI_API_KEY | Provider default |
| Azure OpenAI | Both AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL | No default; the deployment URL is required |
| Mistral | MISTRAL_API_KEY | Provider default |
| Cohere | COHERE_API_KEY | Provider default |
| Groq | GROQ_API_KEY | Provider default |
| Qwen | QWEN_API_KEY | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| DeepSeek | DEEPSEEK_API_KEY | https://api.deepseek.com/v1 |
| Moonshot | MOONSHOT_API_KEY | https://api.moonshot.cn/v1 |
| ChatGLM | ZHIPU_API_KEY | https://open.bigmodel.cn/api/paas/v4 |
| Grok | XAI_API_KEY | https://api.x.ai/v1 |
| Ollama | OLLAMA_ENABLED=true | OLLAMA_BASE_URL, default http://localhost:11434. From 1.8.4, OLLAMA_STRUCTURED_OUTPUTS (dvara.llm-gateway.providers.ollama.structured-outputs, default true) sends json_schema response formats to Ollama; set it to false for an Ollama older than 0.5 |
| Bedrock | BEDROCK_ENABLED=true | Uses AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION; region defaults to us-east-1 |
| Mock | MOCK_PROVIDER_ENABLED=true | Local test provider; do not enable scripted matchers on a production profile |
Gemini, Bedrock and, from 1.8.4, Ollama take image bytes, not an https image URL. The Gateway fetches the URL for them only when you turn fetching on:
| Property | Default | Effect |
|---|---|---|
dvara.llm-gateway.image-fetch.enabled | false | Lets the Gateway fetch an https image URL for providers that need bytes. Off, such a request is refused with 400 unsupported_capability before the call. Private, loopback, link-local and metadata addresses are always refused. |
dvara.llm-gateway.image-fetch.max-bytes | 5242880 | Largest image fetched (5 MB). |
dvara.llm-gateway.image-fetch.timeout | 5s | Time for the whole fetch, redirects included. |
dvara.llm-gateway.image-fetch.content-types | image/png, image/jpeg, image/gif, image/webp | Content types accepted. |
The providers[] entries in Open Source gateway.yaml map to the same provider implementations. A workspace-level credentials map can replace an installation credential for that workspace.
Which routing and resilience properties are supported?
| Property | Default | Availability and effect |
|---|---|---|
dvara.llm-gateway.routes[].strategy | model-prefix | model-prefix, round-robin, weighted, and canary are available by default. latency-aware, cost-aware, geo-aware, and intelligent are Enterprise only. |
dvara.llm-gateway.resilience.enabled | true | Master switch for retry, timeout, circuit breaker, and fallback behavior. |
dvara.llm-gateway.resilience.retry.max-attempts | 3 | Total configured retry attempts. |
dvara.llm-gateway.resilience.retry.initial-backoff-ms | 500 | First retry backoff. |
dvara.llm-gateway.resilience.retry.backoff-multiplier | 2.0 | Backoff multiplier. |
dvara.llm-gateway.resilience.retry.max-backoff-ms | 10000 | Maximum retry backoff. |
dvara.llm-gateway.resilience.circuit-breaker.failure-rate-threshold | 50 | Failure percentage that opens the circuit after the minimum call count. |
dvara.llm-gateway.resilience.circuit-breaker.sliding-window-size | 10 | Calls retained in the circuit-breaker window. |
dvara.llm-gateway.resilience.circuit-breaker.minimum-number-of-calls | 5 | Calls required before failure rate can open the circuit. |
dvara.llm-gateway.resilience.circuit-breaker.wait-duration-in-open-state-ms | 30000 | Delay before the half-open probe. |
dvara.llm-gateway.resilience.circuit-breaker.permitted-calls-in-half-open | 3 | Probe calls allowed while half-open. |
dvara.llm-gateway.resilience.timeout.chat-timeout-ms | 30000 | Whole non-streaming call timeout. |
dvara.llm-gateway.resilience.timeout.streaming-timeout-ms | 120000 | Global value: complete client-visible stream lifetime. A provider override under resilience.providers.<provider> bounds only stream opening. Neither is an idle-between-chunks timeout. |
dvara.llm-gateway.resilience.fallback.enabled | true | Enables automatic fallback across compatible registered providers. It does not activate a route-scoped or named fallback chain. |
Provider-specific overrides live below dvara.llm-gateway.resilience.providers.<provider>.* and use the same retry, circuit-breaker, and timeout fields.
Which rate-limit properties are supported?
| Property | Default | Availability and effect |
|---|---|---|
dvara.llm-gateway.rate-limit.enabled | false | Enables client rate limiting. |
dvara.llm-gateway.rate-limit.per-key.requests-per-minute | 100 | Request refill rate per API key. |
dvara.llm-gateway.rate-limit.per-key.tokens-per-minute | 100000 | Token refill rate per API key. |
dvara.llm-gateway.rate-limit.per-key.requests-burst | same as rate | Maximum accumulated request capacity after an idle period. |
dvara.llm-gateway.rate-limit.per-key.tokens-burst | same as rate | Maximum accumulated token capacity after an idle period. |
dvara.llm-gateway.rate-limit.shared-cache.url | blank | Enterprise distribution only. A non-blank Valkey or Redis URL selects the fleet-wide token bucket. The connection opens on the first governed request. |
dvara.llm-gateway.rate-limit.shared-cache.failure-mode | OPEN | Enterprise shared-cache backend only. OPEN allows traffic when the store is unavailable; CLOSED refuses it. |
The Open Source distribution uses one token bucket per process. A deployment with three replicas can therefore admit about three times the configured rate. The Enterprise embedded backend uses a cluster-wide 60-second sliding window; its burst settings do not apply. The Enterprise shared-cache backend uses a distributed token bucket and applies the burst settings. No Open Source setting turns local counters into shared counters.
A zero per-minute rate disables that dimension in the process and shared-cache token buckets. In the 1.8 Enterprise embedded backend, a zero request rate instead refuses every request; use a positive value or disable rate limiting. A zero burst uses the matching rate as capacity. For Account, Team, and Workspace values in the Enterprise hierarchy, the smallest positive value wins independently for requests and tokens. Use blank fields—not zero—to inherit or clear a Team or Account value until the Flightdeck zero-value behavior is aligned.
The 1.8 shared-cache backend settles completed token usage against the global token settings instead of a narrower workspace override. Do not use that backend as a strict workspace token ceiling.
dvara.llm-gateway.rate-limit.resp.url and dvara.llm-gateway.rate-limit.resp.failure-mode are ignored in 1.8. Merely deploying a cache with the Helm or Compose profile does not select it; set dvara.llm-gateway.rate-limit.shared-cache.url on the Gateway as a separate step. See Control request and token throughput for backend behavior and metrics.
Which priority-admission properties are supported?
These Enterprise settings are read at startup and are off by default.
| Property | Default | Effect |
|---|---|---|
dvara.llm-gateway.routing.priority.enabled | false | Enables concurrency-based admission for chat requests. |
dvara.llm-gateway.routing.priority.max-concurrent-requests | 1000 | Base concurrency used to calculate the current load percentage. |
dvara.llm-gateway.routing.priority.tiers.premium.throttle-threshold-pct | 100 | Starts refusing premium work at this observed load. |
dvara.llm-gateway.routing.priority.tiers.standard.throttle-threshold-pct | 80 | Starts refusing standard work at this observed load. |
dvara.llm-gateway.routing.priority.tiers.bulk.throttle-threshold-pct | 50 | Starts refusing bulk work at this observed load. |
dvara.llm-gateway.routing.priority.resolver-cache-ttl-seconds | 5 | Caches the workspace priority-tier lookup for this many seconds. |
An unset workspace tier uses standard. The 1.8 admission operation is not an atomic hard cap, so a simultaneous burst can cross a threshold.
Which provider-rate-limit properties are supported?
These Enterprise settings observe upstream rate-limit headers and are off by default. Ollama and Bedrock are not tracked in 1.8.
| Property | Default | Effect |
|---|---|---|
dvara.llm-gateway.provider-rate-limit.enabled | false | Enables proactive shedding for credential-based providers after a budget signal has been observed. |
dvara.llm-gateway.provider-rate-limit.token-headroom-pct | 15 | Adds this percentage to the estimated input-token need before admission. |
dvara.llm-gateway.provider-rate-limit.tier.bulk-threshold-pct | 50 | Sheds bulk work at or below this remaining-budget percentage. |
dvara.llm-gateway.provider-rate-limit.tier.standard-threshold-pct | 20 | Sheds standard work at or below this remaining-budget percentage. |
dvara.llm-gateway.provider-rate-limit.tier.premium-threshold-pct | 10 | Sheds premium work at or below this remaining-budget percentage. |
In 1.8, enable priority admission as well when provider shedding must honor workspace tiers. Otherwise every request is treated as standard.
Which PII properties are supported?
| Property | Default | Availability and effect |
|---|---|---|
dvara.llm-gateway.pii.enabled | true | Enables PII scanning. |
dvara.llm-gateway.pii.default-action | LOG | LOG, BLOCK, or REDACT. TOKENIZE is Enterprise only and requires the token store. |
dvara.llm-gateway.pii.scan-responses | true | Scans non-streaming responses. BLOCK refuses a response containing PII with HTTP 400 after provider dispatch. |
dvara.llm-gateway.pii.strip-before-cache | true | Removes detected PII before a supported cache write. |
dvara.llm-gateway.pii.scan-streaming-responses | true | Enables scanning on streamed responses. |
dvara.llm-gateway.pii.streaming-scan-window-size | 256 | Retained for configuration compatibility; ignored by 1.8 whole-response enforcement. |
dvara.llm-gateway.pii.streaming-overlap-margin | 64 | Retained for configuration compatibility; ignored by 1.8 whole-response enforcement. |
dvara.llm-gateway.pii.streaming-max-held-characters | 1000000 | Maximum complete streamed response held when enforcement cannot safely release partial text. |
dvara.llm-gateway.pii.presidio.endpoint | blank | Enterprise detector or a custom integration only. A blank endpoint leaves external NER inactive. Setting it in the Open Source distribution does not add a detector. |
dvara.llm-gateway.pii.presidio.language | en | Used only when an external detector is present. |
dvara.llm-gateway.pii.presidio.score-threshold | 0.5 | Minimum external-detector confidence. |
dvara.llm-gateway.pii.presidio.timeout-seconds | 5 | External-detector timeout. |
dvara.llm-gateway.pii.presidio.cache-max-size | 1000 | Most texts whose Presidio result each Gateway pod keeps in memory; 0 or less turns the cache off. |
dvara.llm-gateway.pii.presidio.cache-ttl-seconds | 300 | Seconds a cached Presidio result is reused; 0 or less turns the cache off. From 1.8.4 a failed analyzer call is never cached. |
dvara.llm-gateway.pii.embedded.enabled | false | Turns on the optional Phileas PII layer. From 1.8.1 the Gateway image carries Phileas, so nothing needs to be built or mounted, and the layer stays off until you set this to true. Flightdeck does not carry the library. |
dvara.llm-gateway.pii.auto-detokenize-response | false | Enterprise TOKENIZE only. On supported non-streaming responses, restores only tokens minted by that request and therefore reintroduces raw PII. It never reverses REDACT or new model output. |
dvara.llm-gateway.pii.max-tokens-per-workspace | 50000 | Enterprise token store only. Use DVARA_LLM_GATEWAY_PII_MAX_TOKENS_PER_WORKSPACE; the old tenant-suffixed environment variable does not bind. Inert in the Open Source distribution. |
dvara.llm-gateway.pii.token-retention-days | 30 | Enterprise persistent token store only. Limits how long reversible tokens remain recoverable. The Open Source distribution has no token vault. |
dvara.llm-gateway.pii.dek-forensic-retention-days | 30 | Enterprise persistent token store only. Retired key material is never retained longer than the token-retention window. |
The Open Source distribution logs a warning when you configure a detector or token-store setting that is not present. It never silently treats TOKENIZE as irreversible redaction.
Which guardrail properties are supported?
| Property | Default | Availability and effect |
|---|---|---|
dvara.llm-gateway.guardrail.enabled | true | Enables prompt-injection and content detection. |
dvara.llm-gateway.guardrail.default-action | LOG | Default result for a detection. Select a stricter action explicitly. |
dvara.llm-gateway.guardrail.scan-responses | true | Scans responses on supported operations. |
dvara.llm-gateway.guardrail.risk-score-threshold | 0.7 | Ignores detections below this score. |
dvara.llm-gateway.guardrail.classifier-action | FLAG | Action for a statistical classifier. INHERIT uses the general guardrail action. |
dvara.llm-gateway.guardrail.max-input-tokens | 0 | Optional fixed input cap. 0 disables this cap; provider context-window governance still applies. |
dvara.llm-gateway.guardrail.max-messages-per-request | 100 | Maximum messages. 0 disables this cap. |
dvara.llm-gateway.guardrail.max-message-length | 50000 | Maximum characters in one message. 0 disables this cap. |
dvara.llm-gateway.guardrail.default-max-response-tokens | 4096 | Applied when a request omits its response-token limit. 0 disables the default. |
dvara.llm-gateway.guardrail.scan-streaming-responses | true | Enables guardrails on streamed responses. |
dvara.llm-gateway.guardrail.streaming-scan-window-size | 256 | Retained for configuration compatibility; ignored by 1.8 whole-response enforcement. |
dvara.llm-gateway.guardrail.streaming-overlap-margin | 64 | Retained for configuration compatibility; ignored by 1.8 whole-response enforcement. |
dvara.llm-gateway.guardrail.embedded.enabled | false | Turns on the optional Phileas guardrail layer. From 1.8.1 the Gateway image carries Phileas, and the layer stays off until you set this to true. Most of its detections score below the default risk threshold of 0.7, so lower the threshold if you want to act on them. |
dvara.llm-gateway.guardrail.ml-classifier.enabled | false | Enterprise only. Enables one configured ML classifier. |
dvara.llm-gateway.guardrail.ml-classifier.provider | generic | Enterprise only. Use defender for the in-process classifier whose model ships in the image. The HTTP options are generic, lakera, shield-gemini, bedrock-guardrails, and aporia. onnx-injection was removed in 1.8.1: with the classifier enabled, that value stops the Gateway from starting, and the message names defender. |
dvara.llm-gateway.guardrail.ml-classifier.defender-model-path | blank | Enterprise only. Points defender at your own copy of the model. Leave it blank to use the copy in the image. |
dvara.llm-gateway.guardrail.ml-classifier.model-path, .injection-class-index | blank | Retired in 1.8.1 along with onnx-injection. They now bind to nothing, and the Gateway names either one in a startup warning if it is still set. |
Enterprise carries the Defender classifier and its model, so defender works with nothing mounted. HTTP classifiers still need their endpoint and credentials. Phileas ships in the Gateway image from 1.8.1, but both of its switches stay off until you turn one on. Managed guardrail plugins, semantic intent checks, and grounding each need their plugin, embedding service, or source documents, and a switch on its own does not add any of them. See ML and plugin guardrails for what startup reports and how each detection behaves.
Which Enterprise Gateway settings matter first?
No configuration setting depends on licence state. See Licensing for rights and capacity limits.
The Enterprise Gateway exposes health,prometheus,gateway-status,info,license through Actuator. The Open Source distribution exposes health,prometheus,gateway-status,info and does not register the licence endpoint. DVARA_ACTUATOR_API_KEY protects gateway status and Enterprise licence health; DVARA_ACTUATOR_METRICS_API_KEY protects Prometheus and must be different.
Keep management.endpoint.health.show-details and every
management.endpoint.health.group.<name>.show-details value at
when-authorized or never. A value of always exposes details to anonymous
probe callers and makes the Gateway refuse readiness; a group-specific value
overrides the endpoint-wide value.
| Property | Environment variable | Default | Effect |
|---|---|---|---|
dvara.license.key | DVARA_LICENSE_KEY | blank | Signed licence envelope. From 1.8.2 Flightdeck copies it into its licence store once, when none is stored, and ignores it after that; the Gateway does not read it. Set the licence on Flightdeck's License page instead. No restart is needed. |
dvara.data-plane.control-plane.base-url | DVARA_DATA_PLANE_CONTROL_PLANE_BASE_URL | blank | Flightdeck's /internal address, for example https://flightdeck:8443. Required from 1.8.2: the Gateway refuses to start without it. See what a Gateway needs. |
dvara.llm-gateway.local-store.path | DVARA_LLM_GATEWAY_LOCAL_STORE_PATH | blank | The spool file, on a volume that survives a restart. Required from 1.8.2. |
spring.datasource.url | SPRING_DATASOURCE_URL | unset | Flightdeck only. From 1.8.2 a Gateway given a database URL refuses to start and names the setting. |
| — | DVARA_DB_MIGRATE, DVARA_DB_POOL_SIZE, DVARA_DB_SOCKET_TIMEOUT_SECONDS | — | No longer read from 1.8.2. The Gateway has no database, and Flightdeck is the only process that migrates the schema. |
dvara.license.degradation.data-plane-prefixes, dvara.license.degradation.message | mechanical conversion | — | Removed in 1.8.2 and bind to nothing. An expired licence no longer refuses any path. |
dvara.credentials.require-workspace-credential | DVARA_CREDENTIALS_REQUIRE_TENANT_CREDENTIAL | false | When true, a workspace without its own active provider credential receives 403 WORKSPACE_CREDENTIAL_REQUIRED instead of borrowing the platform credential. |
dvara.audit.max-events | DVARA_AUDIT_MAX_EVENTS | 100000 | Maximum signed envelopes retained in process memory. A configured durable sink is not truncated by this limit. |
dvara.audit.store-prompts-by-default | DVARA_AUDIT_STORE_PROMPTS | false | Prompt storage is not implemented in 1.8.1. No audit event carries a prompt, so turning this on keeps nothing, and the Gateway logs one warning at startup that says so. |
dvara.audit.prompt-retention-days | DVARA_AUDIT_PROMPT_RETENTION_DAYS | 90 | Nothing reads this yet, because nothing stores a prompt. It is the retention that will apply once prompt storage arrives. |
dvara.llm-gateway.cache.enabled | DVARA_LLM_GATEWAY_CACHE_ENABLED | false | Exact-match response cache. |
dvara.llm-gateway.cache.ttl-seconds | DVARA_LLM_GATEWAY_CACHE_TTL_SECONDS | 3600 | Exact-match cache lifetime. |
dvara.llm-gateway.cache.max-size | DVARA_LLM_GATEWAY_CACHE_MAX_SIZE | 10000 | Exact-match cache entry limit. |
dvara.llm-gateway.cache.semantic.enabled | mechanical conversion | true | Enables the semantic cache implementation. Similarity-only serving remains off by default. |
dvara.llm-gateway.cache.semantic.similarity-serving | mechanical conversion | false | Allows a topically similar request to reuse a response. Keep false when semantic equivalence matters. |
dvara.llm-gateway.cache.semantic.config-cache-ttl-seconds | DVARA_LLM_GATEWAY_CACHE_SEMANTIC_CONFIG_CACHE_TTL_SECONDS | 60 | Maximum time a Gateway pod reuses the resolved workspace/model threshold. An edit can take this long to affect the pod. Set 0 to read the persisted threshold on every request. |
dvara.llm-gateway.ip-access.enabled | DVARA_LLM_GATEWAY_IP_ACCESS_ENABLED | false | Enables IP rules. |
dvara.llm-gateway.ip-access.scope | DVARA_LLM_GATEWAY_IP_ACCESS_SCOPE | all | all or data-plane; deny rules are evaluated before allow rules. |
dvara.llm-gateway.tls.enforce-tls13 | DVARA_LLM_GATEWAY_TLS_ENFORCE_TLS13 | true | Enforces TLS 1.3 for provider connections. |
dvara.llm-gateway.webhooks.enabled | DVARA_LLM_GATEWAY_WEBHOOKS_ENABLED | true | Enables delivery for webhooks that have been configured. |
dvara.llm-gateway.webhooks.max-retries | DVARA_LLM_GATEWAY_WEBHOOKS_MAX_RETRIES | 3 | Maximum delivery retries. |
dvara.llm-gateway.webhooks.delivery-timeout-ms | DVARA_LLM_GATEWAY_WEBHOOKS_DELIVERY_TIMEOUT | 5000 | Per-delivery timeout. |
Which A2A streaming settings are supported?
These settings apply only to the Enterprise A2A plane, which runs with or without a licence. The same bounds govern message:stream and tasks:resubscribe.
| Property | Default | Effect |
|---|---|---|
a2a.streaming.enabled | true | Set it to false to close both streaming doorways. message:stream and tasks:resubscribe then answer one SSE error event, a2a_streaming_disabled, before the caller is even authenticated, and startup logs a warning. Enforced from 1.8.1; earlier releases accepted the setting and ignored it. |
a2a.streaming.max-held-characters | 1000000 | Maximum detector-visible text retained for one response. |
a2a.streaming.max-held-bytes | 8000000 | Maximum serialized response bytes retained while delivery is Deferred. |
a2a.streaming.max-held-events | 20000 | Maximum event objects retained while delivery is Deferred. |
a2a.streaming.connect-timeout-seconds | 10 | Maximum time allowed to connect to the peer stream. |
a2a.streaming.read-timeout-seconds | 300 | Read/idle timeout for the upstream peer stream. |
a2a.streaming.scan-window-size | 256 | Accepted for compatibility but ignored by 1.8 whole-response enforcement. |
a2a.streaming.overlap-margin | 64 | Accepted for compatibility but ignored by 1.8 whole-response enforcement. |
a2a.streaming.resume-carry-characters | 256 | From 1.8.5. How much of the end of each text body a task's stream keeps for a resume. A tasks:resubscribe stream is scanned together with it, so a value split at the break is still caught. Kept in the pod's memory, per workspace, agent and task, for up to 10,000 tasks and one hour. 0 keeps nothing. |
Under PII LOG, DVARA releases events immediately and retains a bounded prefix
for final evidence. Crossing the character bound stops further scanning,
continues delivery, and records scan_incomplete. Under PII BLOCK, REDACT,
or TOKENIZE, DVARA holds the complete structured response; crossing any hold
bound stops the stream without releasing the held response.
Which A2A delegation settings are supported?
From 1.8.3, the A2A delegation guard reads a2a.delegation.mode (default
enforce), a2a.delegation.cycle-rule (default agent-skill),
a2a.delegation.max-depth (default 8) and
a2a.delegation.require-chain-for-agents (default false) as fleet defaults
that each workspace can override, plus a2a.delegation.chain-ttl (default
15m). The chain is signed with DVARA_A2A_DELEGATION_SIGNING_SECRET, or with
a key derived from the audit HMAC secret when that is unset. From 1.8.4 the
secret that gives the key must be at least 32 bytes and must not be a
placeholder DVARA publishes. Otherwise a Gateway on a production profile
refuses to start, and on a dev, test, ci, local or default profile it
logs a warning and runs the guard as off. The
delegation guard
page explains each value and when to use observe.
From 1.8.5 three more settings work the same way, as fleet defaults that each workspace can override in the Flightdeck workspace form or on the Flightdeck's A2A Delegation page:
| Property | Default | Effect |
|---|---|---|
a2a.delegation.preset | standard | standard leaves every setting as set. hardened makes agent keys send their chain and treats any repeat of an agent as a cycle (cycle-rule agent), whatever those two settings say. It also turns on the session hop limit, at 200 unless you set your own. mode and max-depth still apply, so you can run hardened in observe first. |
a2a.delegation.max-hops-per-session | 0 (no limit) | The most hops one session may forward, for every tier, from 0 to 1,000,000. Hops spread over Gateways count together. Only hops forwarded to a peer count. Past the limit a hop is refused with 409 A2A_DELEGATION_HOP_BUDGET_EXCEEDED. This is a safety limit; billing does not change. |
a2a.delegation.hop-budget-timeout | 100ms | How long a hop waits for the shared count. When it cannot be read in time, a hardened workspace refuses the hop with 503 A2A_DELEGATION_HOP_BUDGET_UNAVAILABLE. Other workspaces let it through, log a warning and count dvara_a2a_hop_budget_unavailable_total. |
Which A2A push and endpoint settings are new in 1.8.5?
From 1.8.5 a peer's push notification goes to the Gateway, which checks, scans
and audits it before it passes it on to the workspace's webhook. A2A peers must
also be https://. See native A2A.
| Property | Environment variable | Default | Effect |
|---|---|---|---|
a2a.push.callback-base-url | A2A_PUSH_CALLBACK_BASE_URL | unset | The Gateway's public URL as peers reach it. Unset, a push config is refused with 503 A2A_PUSH_NOT_AVAILABLE, except in a workspace that chose direct delivery. In the Helm chart, set llmGatewayServer.a2a.pushCallbackBaseUrl. |
a2a.push.delivery-attempts | mechanical conversion | 3 | Attempts to deliver a notification to the workspace's webhook. If all fail, the peer gets 502 and can send again. |
a2a.push.max-body-bytes | mechanical conversion | 1048576 | The largest notification read (1 MiB). A larger one is refused with 413 A2A_PUSH_TOO_LARGE. |
dvara.a2a.allow-plaintext-endpoints | DVARA_A2A_ALLOW_PLAINTEXT_ENDPOINTS | false | Allows http:// peers, for local stacks whose stub peers have no certificate. Works only on a development profile (dev, test, ci, local, or none). The production profile that Compose and the chart set ignores it. Set it on Flightdeck and the Gateway alike. |
A workspace keeps direct delivery, peer to webhook, with its setting
a2a.push.delivery=direct. Those notifications are then not scanned, audited
or recorded by DVARA.
Which MCP settings are new in 1.8.4 and 1.8.5?
These settings apply only to the Enterprise MCP plane, which runs with or without a licence.
| Property | Default | Effect |
|---|---|---|
dvara.mcp-gateway.agentic.approval.progress-interval-ms | 5000 | How often a native /mcp tools/call held for approval gets an MCP notifications/progress. Sent only when the call's _meta carries a progressToken. |
dvara.mcp-gateway.extensions.allowed (DVARA_MCP_GATEWAY_EXTENSIONS_ALLOWED) | empty, which allows nothing | The fleet-wide MCP extension allow-list. Entries are vendor/name, vendor/* or vendor/name@version. DVARA serves no extension yet, so nothing is granted. |
dvara.mcp-gateway.legacy-sse-sunset (DVARA_MCP_GATEWAY_LEGACY_SSE_SUNSET) | 2027-07-28 | From 1.8.5. The first day (UTC) DVARA refuses to reach an upstream server over the legacy HTTP+SSE transport. From that date a call is refused with 410 mcp_transport_sunset and a tool sync fails. Set it on the Gateway and on Flightdeck. |
dvara.mcp-gateway.input-requests.elicitation | allow | From 1.8.5. Whether a server's request for user input (elicitation/create) is relayed to the caller on the REST surface. allow or refuse. |
dvara.mcp-gateway.input-requests.roots | refuse | From 1.8.5. The same for a request for the client's filesystem roots (roots/list). |
dvara.mcp-gateway.input-requests.max-request-state-bytes | 16384 | From 1.8.5. The largest requestState relayed either way (16 KiB). |
A workspace can replace the fleet list with its mcp.extensions.allowed key, set
on the Flightdeck workspace form or on the Flightdeck's Agents → MCP Extensions
page. Blank inherits the fleet list and none allows nothing. A malformed entry
is refused on save and on a GitOps import. See
MCP extensions.
How large a request or response can be
| Property | Default | Effect |
|---|---|---|
a2a.limits.max-message-length | 50000 | The most text one outbound A2A message may carry, counted across all of its text parts. 0 or less turns the cap off. |
A message over the limit is refused with 413 A2A_MESSAGE_TOO_LARGE, and the
message names both numbers. The check runs before policy and the PII scan, on
message:send and on message:stream, and the refusal is audited and recorded
as a hop like any other refusal.
The cap arrived in 1.8.1. Before it, the plane had no size limit at all, and a
very large message could hold a Gateway thread for minutes inside the PII scan.
The default matches the LLM plane's guardrail.max-message-length, so an
agent that fits one fits the other.
From 1.8.5 an MCP tool call has an argument limit, and each plane limits how
much of an upstream's answer it reads. From 1.8.6 the native MCP endpoint also
limits the complete request body. 0 turns a limit off.
| Property | Environment variable | Default | Past the limit |
|---|---|---|---|
dvara.mcp-gateway.limits.max-request-bytes | DVARA_MCP_GATEWAY_LIMITS_MAX_REQUEST_BYTES | 4194304 (4 MiB) | Bare HTTP 413 on native POST /mcp, before JSON-RPC processing |
dvara.mcp-gateway.limits.max-arguments-bytes | DVARA_MCP_GATEWAY_LIMITS_MAX_ARGUMENTS_BYTES | 1048576 (1 MiB) | 413 MCP_ARGUMENTS_TOO_LARGE, before the schema check, policy, the PII scan and the server |
dvara.llm-gateway.response-limits.max-body-bytes | DVARA_LLM_GATEWAY_RESPONSE_LIMITS_MAX_BODY_BYTES | 67108864 (64 MiB) | 502 PROVIDER_RESPONSE_TOO_LARGE |
dvara.llm-gateway.response-limits.max-stream-bytes | DVARA_LLM_GATEWAY_RESPONSE_LIMITS_MAX_STREAM_BYTES | 134217728 (128 MiB) | 502 PROVIDER_RESPONSE_TOO_LARGE |
dvara.mcp-gateway.response-limits.max-body-bytes | DVARA_MCP_GATEWAY_RESPONSE_LIMITS_MAX_BODY_BYTES | 4194304 (4 MiB) | 502 MCP_RESPONSE_TOO_LARGE |
dvara.mcp-gateway.response-limits.max-stream-bytes | DVARA_MCP_GATEWAY_RESPONSE_LIMITS_MAX_STREAM_BYTES | 16777216 (16 MiB) | 502 MCP_RESPONSE_TOO_LARGE |
a2a.response-limits.max-body-bytes | A2A_RESPONSE_LIMITS_MAX_BODY_BYTES | 16777216 (16 MiB) | 502 A2A_RESPONSE_TOO_LARGE |
a2a.response-limits.max-stream-bytes | A2A_RESPONSE_LIMITS_MAX_STREAM_BYTES | 67108864 (64 MiB) | 502 A2A_RESPONSE_TOO_LARGE; the stream ends with an error event |
The max-body-bytes limits cover a whole answer; the max-stream-bytes limits
cover a streamed answer, and on the LLM plane a file download such as a batch's
results. A refused answer is not retried. A provider answer over the limit does
not count against the provider's circuit. The MCP limits cover every upstream
transport and the tool sync; the A2A limits cover hops, streams, task calls and
Agent Card fetches. The MCP default is lower because a multi-megabyte tool
result takes seconds to read, and a larger limit would time out before it
refused.
The MCP request limit covers the whole native POST /mcp body, not the
server-scoped REST bridge. DVARA checks authentication before reading the body,
so a bad credential still receives 401. A declared or chunked body over the
limit receives 413 without a DVARA JSON error code. Because this outer limit
includes the tool arguments, a workspace argument limit above 4 MiB has no
effect on native calls unless you raise the outer limit too.
A workspace can set its own MCP argument limit and its own MCP and A2A response
limits: mcp.limits.max-arguments-bytes, mcp.response-limits.max-body-bytes,
mcp.response-limits.max-stream-bytes, a2a.response-limits.max-body-bytes and
a2a.response-limits.max-stream-bytes. Set them in the Size limits section
of the Flightdeck workspace form. A positive whole number replaces the fleet value,
lower or higher; the form and a GitOps import refuse anything else. The LLM
limits are fleet-wide only.
On upgrade to 1.8.5: a tool call with more than 1 MiB of arguments, an MCP tool result over 4 MiB, an A2A answer over 16 MiB and an A2A stream over 64 MiB are refused where they used to be read whole.
On upgrade to 1.8.6: a native MCP request over 4 MiB is refused before JSON-RPC processing, where the Gateway previously buffered the complete body.
Configure an external credential store
Set dvara.vault.backend to hashicorp, aws-secrets-manager, or azure-key-vault. A blank value disables external credential lookup.
| Property | Environment variable | Default |
|---|---|---|
dvara.vault.cache-ttl-seconds | DVARA_VAULT_CACHE_TTL | 300 |
dvara.vault.hashicorp.address | VAULT_ADDR | blank |
dvara.vault.hashicorp.token | VAULT_TOKEN | blank |
dvara.vault.hashicorp.namespace | VAULT_NAMESPACE | blank |
dvara.vault.hashicorp.secret-path | VAULT_SECRET_PATH | secret/data/dvara |
dvara.vault.hashicorp.auth-method | VAULT_AUTH_METHOD | token |
dvara.vault.aws.region | AWS_VAULT_REGION | us-east-1 |
dvara.vault.aws.secret-name | AWS_SECRET_NAME | dvara/provider-credentials |
dvara.vault.azure.vault-url | AZURE_VAULT_URL | blank |
dvara.vault.azure.client-id | AZURE_CLIENT_ID | blank |
dvara.vault.azure.client-secret | AZURE_CLIENT_SECRET | blank |
dvara.vault.azure.tenant-id | AZURE_TENANT_ID | blank |
For Azure Key Vault, tenant-id is the Microsoft Entra tenant that owns the app registration—not a DVARA workspace ID. Use AZURE_TENANT_ID=<tenant-id> in deployment configuration.
Backend credentials are prerequisites, not feature switches. Prefer workload identity or the provider’s default credential chain where supported instead of static keys.
When does a bootstrap file run?
DVARA_BOOTSTRAP_FILE is the canonical variable. The older GATEWAY_BOOTSTRAP_FILE remains an accepted fallback in 1.8, but new deployments should not use it.
| Gateway configuration mode | What happens when a bootstrap file is set |
|---|---|
| Flightdeck | DVARA reads the file at Flightdeck startup, creates missing workspaces, API keys, and routes in its database, and skips identities that already exist. The next bundle carries them to the Gateways. It is initial seeding, not continuous reconciliation. |
Open Source gateway.yaml store | The repositories are read-only. The bootstrap variable is accepted only when it names the same file as DVARA_CONFIG_FILE; the file is already the active configuration and is not copied anywhere. A different file refuses startup. |
| Enterprise Gateway | From 1.8.2 the Gateway refuses to start when DVARA_BOOTSTRAP_FILE or GATEWAY_BOOTSTRAP_FILE is set, and names the setting. Set the file on Flightdeck instead. |
The schemas remain different: use gateway.yaml to serve an Open Source configuration and bootstrap.yaml only to seed Flightdeck.
What does a Gateway need without a database?
From 1.8.2 an Enterprise Gateway has no database. It reads its configuration from the signed bundle Flightdeck publishes, and writes audit, usage and cost to a local spool that it ships to Flightdeck. See How the gateway runs without a database.
| Responsibility | Setting | Default |
|---|---|---|
| Reach Flightdeck for configuration and to drain the spool | dvara.data-plane.control-plane.base-url | blank; required, the Gateway refuses to start without it |
| Keep audit and telemetry while disconnected | dvara.llm-gateway.local-store.path | blank; required, the Gateway refuses to start without it |
Enrol with Flightdeck for the /internal certificate | dvara.data-plane.control-plane.enrolment.shared-secret (the same value as Flightdeck's dvara.internal.enrolment.shared-secret, at least 32 characters) or a one-time dvara.data-plane.control-plane.enrolment.token | blank |
| Keep the enrolled key and certificate | dvara.data-plane.control-plane.enrolment.directory, on a persistent volume. Setting it turns enrolment on for the pod. | blank |
| Verify configuration | dvara.data-plane.control-plane.public-key | blank; optional, because enrolment delivers the key. A key you set wins. |
dvara.data-plane.serve-from-bundle is always on for an Enterprise Gateway from
1.8.2. Setting it to false refuses startup.
Flightdeck's side of enrolment:
| Property | Default | Effect |
|---|---|---|
dvara.internal.enrolment.enabled | false | Creates Flightdeck's own certificate authority and serves /internal on the enrolment port. The Compose file and the Helm chart turn it on. |
dvara.internal.enrolment.port | 8443 | The HTTPS port for enrolment and /internal. |
dvara.internal.enrolment.server-names | flightdeck, localhost, plus the host name | Names in Flightdeck's server certificate. Set them to what Gateways put in base-url. |
dvara.internal.enrolment.shared-secret | blank | The shared secret Gateways enrol with. At least 32 characters, or Flightdeck refuses to start. |
dvara.internal.enrolment.token-ttl | 24h | How long a one-time token from the Flightdeck's Gateway Enrolment page is valid. |
dvara.internal.enrolment.certificate-validity | 30d | Validity of Gateway and server certificates. Gateways renew their own. |
Local-spool throughput and capacity are per Gateway pod:
| Property | Default | Effect |
|---|---|---|
dvara.llm-gateway.local-store.drain-interval-ms | 30000 | Fixed delay between drain passes |
dvara.llm-gateway.local-store.drain-batch-size | 500 | Records per batch; one pass continues for up to 20 full batches or 10 seconds |
dvara.llm-gateway.local-store.max-sheddable-records | 500000 | Bound across usage, cost, and observability records; audit records are never shed |
At the defaults, a pod can drain about 10,000 records per pass. When the
sheddable bound is full, DVARA drops lower-tier records to make room and
increments gateway_spool_shed_total{class}. Monitor
gateway_drain_lag_seconds, which reports the age of the oldest unshipped
record across all drained classes.
Useful bundle settings:
| Property | Default | Effect |
|---|---|---|
dvara.data-plane.control-plane.poll-interval-ms | 5000 | Bundle version poll interval. |
dvara.data-plane.control-plane.deny-list-poll-interval-ms | 5000 | From 1.8.5. How often the Gateway polls the revocation list, and so how fast a revocation or a session kill lands. Before 1.8.5 the list polled every 10 seconds. When this is unset and poll-interval-ms is set, the list keeps that value. |
dvara.data-plane.control-plane.staleness-warn-seconds | 3600 | Age at which /actuator/gateway-status reports the active bundle as stale. It warns; it does not stop traffic. |
dvara.data-plane.control-plane.snapshot-path | blank | Persists the last verified bundle for cold start during a control-plane outage. Use a durable volume in production. |
dvara.data-plane.control-plane.deny-list-url | control-plane base URL | Optional independent revocation channel. Using the same URL shares its failure mode. |
dvara.data-plane.control-plane.ingest-url | control-plane base URL | Optional separate destination for audit and telemetry ingestion. |
From 1.8.2 only Flightdeck checks the database for changes, with dvara.config.poll-interval-ms (default 3000), and republishes the bundle when something changed, checking every dvara.config.bundle.republish-interval-ms (default 5000). A Gateway does not register these pollers.
Which session-kill settings are new in 1.8.5?
From 1.8.5 a session kill stops the session on the LLM, MCP and A2A planes, on every Gateway, for 24 hours. See Stop an agent session.
| Property | Environment variable | Default | Effect |
|---|---|---|---|
dvara.internal.deny-list.session-kill-retention | mechanical conversion | 24h | How long a kill lasts, on Flightdeck and on every Gateway. Set the same value on both. Replaces dvara.internal.deny-list.session-retention-margin-minutes, which gave a kill 75 minutes. |
dvara.cluster.members | DVARA_CLUSTER_MEMBERS | unset | A comma-separated list of Gateway host or host:port entries that form one cluster. When set, it wins over every other discovery method. Use it on VMs and Compose where multicast is blocked. |
dvara.cluster.instance-name | mechanical conversion | dvara-gateway | The Gateway's name in the cluster. |
dvara.cluster.port | mechanical conversion | unset | A fixed cluster port for the Gateway. |
dvara.agentic.loop-detection.cluster-timeout | mechanical conversion | 50ms | How long a loop check waits for the session's shared history. When it does not answer, the Gateway judges the call on its own history and counts dvara_loop_detector_fallback_total. A loop check never fails a call. |
Gateways in one cluster pass a kill to each other within milliseconds. The
revocation list stays the authority, so a kill still arrives, within one poll,
when the cluster is absent or split. /actuator/gateway-status reports the
cluster size in its sessionKills section, so a fleet of one-member clusters is
visible.
Which Flightdeck process settings are supported?
| Property | Environment variable | Default | Effect |
|---|---|---|---|
server.port | SERVER_PORT | 8090 | Flightdeck HTTP port. |
spring.session.timeout | SPRING_SESSION_TIMEOUT | 4h | Server-side timeout for built-in, OIDC, and SAML browser sessions. |
dvara.flightdeck.gateway.url | DVARA_FLIGHTDECK_GATEWAY_URL | http://localhost:8080 | Gateway base URL used by Flightdeck. |
dvara.flightdeck.gateway.connect-timeout-ms | mechanical conversion | 5000 | Connection timeout for Flightdeck-to-Gateway calls. |
dvara.flightdeck.gateway.read-timeout-ms | mechanical conversion | 10000 | Read timeout for Flightdeck-to-Gateway calls. |
dvara.flightdeck.playground.enabled | DVARA_FLIGHTDECK_PLAYGROUND_ENABLED | true | Enables ad hoc model calls from the Flightdeck. Disable when operators should not make them. |
dvara.flightdeck.portal.enabled | mechanical conversion | true | Enables workspace-scoped Flightdeck pages routes. |
dvara.flightdeck.portal.self-service | mechanical conversion | true | Allows workspace users to create supported resources in the Flightdeck. |
dvara.flightdeck.security.enabled | mechanical conversion | true | Uses OIDC when an issuer is configured; otherwise uses built-in authentication. Set false only for local development. |
dvara.flightdeck.security.rbac.enabled | mechanical conversion | true | Enforces roles on authenticated administrative routes. |
dvara.flightdeck.security.oidc.issuer-uri | mechanical conversion | blank | Activates OIDC when security is enabled. |
dvara.flightdeck.security.saml.metadata-url | DVARA_FLIGHTDECK_SECURITY_SAML_METADATA_URL | blank | Activates SAML. Configuring OIDC and SAML together is refused at startup. |
spring.servlet.multipart.max-file-size | mechanical conversion | 25MB | Maximum configuration-import upload. The request-size limit is also 25MB. |
dvara.flightdeck.catalog.tiers[].caps.monthly-llm-calls, .monthly-mcp-calls, .monthly-a2a-calls | configured in the tier catalogue | per tier | Monthly governed-call quota bands. A value of 0 means unlimited. |
dvara.flightdeck.catalog.tiers[].blocks-at-hard-cap | configured in the tier catalogue | per tier | Decides whether a tier blocks after its hard-cap threshold. |
dvara.flightdeck.audit-archive.* | mechanical conversion | disabled | Configures audit archival. Cost and token-usage records use the workspace audit retention or a fixed 400-day floor, whichever is longer. No shipped 1.8 image packages the optional S3 client required to start it. |
Use the identity-provider guides for the complete OIDC or SAML claim mapping. Email and compliance scheduling are separate operational workflows. Configure audit archival on its canonical page rather than copying a partial example from this reference.
Where do workspace overrides belong?
Which security-sensitive settings need an explicit decision?
| Property | Default | Distribution | Effect |
|---|---|---|---|
dvara.llm-gateway.ip-access.trust-forwarded-for | false | Enterprise | Uses the forwarded client address. Enable only behind a proxy that strips caller-supplied forwarding headers. |
dvara.llm-gateway.ip-access.global-allowlist / .global-denylist | empty | Enterprise | Global CIDR rules applied before workspace rules. |
dvara.pii.token-encryption-master-password | blank | Enterprise | Without it, TOKENIZE cannot mint a token and pii.degraded-action applies (BLOCK by default). |
dvara.pii.key-source | local | Enterprise | Selects local or KMS-backed token key custody. |
dvara.pii.kms.key-id, .region, .access-key, .secret-key | blank | Enterprise | KMS key and optional explicit AWS credentials. |
dvara.llm-gateway.local-store.pii-high-water-per-workspace | 40000 | Enterprise | Stops minting more tokens for a workspace at this depth and applies degraded action. |
dvara.internal.mtls.enabled / .log-rejections | false / true | Enterprise | Enables the internal channel and records rejected client certificates. |
dvara.llm-gateway.pii.token-mode | vault | Enterprise | self-contained sends encrypted PII token ciphertext across the provider boundary. |
dvara.flightdeck.security.saml.signing.certificate / .private-key | blank | Enterprise | Required when the IdP requests signed authentication requests. |
dvara.flightdeck.security.builtin.max-failed-attempts / .lockout-duration-minutes | 5 / 15 | Enterprise | Built-in account lockout policy. |
dvara.llm-gateway.cache.in-memory.enabled | false | Open Source | Enables the process-local exact response cache. |
dvara.llm-gateway.cache.in-memory.max-entries / .ttl-seconds | 1000 / 300 | Open Source | Bounds entries and lifetime; restart clears the cache. |
In the Open Source distribution, put these keys in workspaces[].metadata inside gateway.yaml. In the Enterprise platform, use the matching Flightdeck settings page. Enterprise typed settings take precedence over legacy metadata values.
| Key | Default or values | Condition |
|---|---|---|
pii.enabled | global default | Applies to this workspace. |
pii.action | LOG, BLOCK, REDACT, or Enterprise TOKENIZE | LOG is the default. REDACT is irreversible; TOKENIZE needs a token store and key material. Path-specific response behavior still applies. |
pii.scan-responses | global default | Controls response scanning. |
pii.auto-detokenize-response | false | Enterprise TOKENIZE only; restores request-minted tokens on supported non-streaming responses. |
pii.degraded-action | BLOCK or LOG; default BLOCK | Enterprise TOKENIZE only. Determines whether to refuse or expose raw input when a token cannot be minted. |
pii.custom-patterns | JSON map | Pattern names map to regular expressions. |
guardrail.enabled | global default | Enables workspace guardrails. |
guardrail.action | LOG, FLAG, or BLOCK | Determines whether a detection records, flags, or refuses on supported paths. |
guardrail.risk-score-threshold | global default | Number from 0.0 to 1.0. |
rate-limit.requests-per-minute | global default | Per-workspace override applied to its API keys. |
rate-limit.tokens-per-minute | global default | Per-workspace token override. |
credentials.require-workspace-credential | global default | Enterprise strict-BYOK override. |
cost.per-call-max-usd | 0, disabled | Enterprise per-request cost ceiling; accurate pricing is required. |
ip-access.allowlist | comma-separated CIDRs | Enterprise IP control; empty means no workspace allowlist. |
ip-access.denylist | comma-separated CIDRs | Enterprise denylist; evaluated before allowlist. |
data-residency.allowed-regions | comma-separated region IDs | Enterprise. Empty or absent means no workspace residency restriction. |
audit.store-prompts | false unless changed | Enterprise. Prompt storage is not implemented in 1.8.1, so this keeps nothing; a workspace that turns it on is named once in a startup warning. |
approval.required-tools | comma-separated glob patterns | Enterprise MCP approval rule. The MCP plane runs with or without a licence. |
approval.required-servers | comma-separated server IDs | Enterprise MCP approval rule. |
agentic.loop-detection.enabled | workspace or global default | Enterprise agentic governance. |
agentic.loop-detection.auto-kill | false | Enterprise. Detection records without terminating a session unless enabled. |
Use the governance guides for the full set of typed workspace controls. A field appearing in an import document does not make its feature available in the Open Source distribution.
Which old settings should you remove?
| Old setting | 1.8 behavior | Replacement |
|---|---|---|
dvara.llm-gateway.data-plane.require-api-key / DVARA_LLM_GATEWAY_REQUIRE_API_KEY | Removed. Every /v1 request requires a key. A false value refuses startup; true is tolerated as dead configuration during migration. | Remove the setting, mint a key for every caller, and store only its fingerprint. |
gateway.server.api-key | Not the canonical actuator namespace | dvara.actuator.api-key / DVARA_ACTUATOR_API_KEY |
gateway.server.metrics-api-key | Not the canonical actuator namespace | dvara.actuator.metrics-api-key / DVARA_ACTUATOR_METRICS_API_KEY |
management.otlp.tracing.endpoint | Ignored by the 1.8 runtime | management.opentelemetry.tracing.export.otlp.endpoint or OTEL_EXPORTER_OTLP_ENDPOINT |
dvara.llm-gateway.rate-limit.resp.url | Ignored | dvara.llm-gateway.rate-limit.shared-cache.url in the Enterprise distribution |
dvara.llm-gateway.rate-limit.resp.failure-mode | Ignored | dvara.llm-gateway.rate-limit.shared-cache.failure-mode in the Enterprise distribution |
DVARA_LLM_GATEWAY_PII_MAX_TOKENS_PER_TENANT | Does not bind to the renamed workspace property | DVARA_LLM_GATEWAY_PII_MAX_TOKENS_PER_WORKSPACE |
dvara.llm-gateway.region.id | Accepted as a deprecated alias; conflicting region values refuse startup | dvara.region.id |
api_keys[].key in gateway.yaml | Refused; plaintext API keys are no longer accepted | Generate a key and store key_hash |
api_keys[].generate in gateway.yaml | Refused; generated keys would change at restart | Generate the key before startup and store key_hash |
output_schemas[].max_retries | Ignored | Remove it; schema validation does not read this field |
output_schemas[].correction_prompt | Ignored | Remove it |
| Separate MCP or A2A service ports | No effect in the unified Enterprise Gateway | Send MCP and A2A traffic to Gateway port 8080 |
Unknown fields in gateway.yaml can be ignored unless validation explicitly rejects them. Treat a clean startup as necessary but not sufficient: send a governed test request and verify its response, audit event, and metrics before relying on a configuration change.
How do you verify a setting took effect?
- Check
/actuator/health/readinessafter startup or rollout. - Call
/actuator/gateway-statuswithDVARA_ACTUATOR_API_KEYto inspect providers, routes, limits, region, warnings, and bundle state. - For the Enterprise posture and licence health, call
/actuator/licensewith the same operator key. - Exercise the affected request path with a safe test input.
- Verify the resulting audit event and metric. A setting name alone does not prove that a capability is active.
Start with Configure DVARA safely for the change workflow, and check Capability availability before enabling a distribution-specific control.