Configuration Reference

oguardai.yaml

The primary configuration file controls all server behavior. Pass it with --config oguardai.yaml when starting the server.

Parsing is strict and fails closed. An unrecognized top-level key aborts startup with an error that names it, and nested sections such as tenants reject an unknown or misspelled key the same way. The server never silently drops a setting it validates, so a typo like allowed_polcies cannot quietly disable a control and leave the server running with an unintended default.

server:
  host: "127.0.0.1"          # loopback under dev auth; a real auth mode may bind 0.0.0.0
  port: 3000

auth:
  mode: dev                  # dev | api_key | jwt | oidc

session:
  backend: sealed            # sealed | memory | redis (managed is planned)
  ttl_seconds: 3600

detector:
  mode: builtin              # builtin | both | advanced
  # advanced_url is unset by default; set it to the Python NER sidecar
  # URL when mode is both or advanced, e.g. http://detector:9090

policy:
  default: default
  directory: ./policies
  watch: false

transform:
  context_strategy: full
  max_context_tokens: 4096
  shadow_mode: false

output_protection:
  enabled: true   # Enabled by default; set false to disable
  mode: strict
  default_action: mask
  exempt_types: []   # Only 'url' is exemptible (component-scanned before forwarding)
  encoded_content_action: allow   # Posture for encoded runs the model emits (base64 that decodes to text, or percent-escape runs)
  opaque_payload_action: allow    # Posture for base64 runs that decode to non-text binary (encrypted, compressed, image bytes)

prompt_security:
  enabled: true
  input_scanning: true
  action: strip

file_upload:
  max_size_bytes: 52428800   # 50MB

rate_limit:
  enabled: false
  requests_per_second: 100
  burst_size: 200

Server

server:
  host: "127.0.0.1"    # default; a real auth mode may bind 0.0.0.0
  port: 3000
  allowed_origins:
    - "https://app.example.com"
  max_body_size_bytes: 10485760
  tls:
    enabled: true
    cert_path: /etc/guardai/tls/server.crt
    key_path: /etc/guardai/tls/server.key

Auth

Do not use auth.mode: dev in production. Always set a real auth mode and API keys for production deployments.

API keys (auth.api_keys)

In api_key mode, callers authenticate with the X-API-Key header and each key is declared under auth.api_keys. Starting in api_key mode with no keys configured aborts startup.

auth:
  mode: api_key
  api_keys:
    - key: "sk-live-a1b2c3..."      # the raw secret compared in constant time
      identity: "billing-service"    # identity label recorded in the audit log
      name: "production-key-1"        # optional human-readable label
      tenant_id: "acme-corp"          # optional tenant scope for multi-tenancy
      scopes: [transform, rehydrate, detect]
      caller_role: "support-agent"    # optional; overrides any request-supplied caller_role
      caller_purpose: "support"       # optional; overrides any request-supplied caller_purpose

Keys can also be injected from the environment (for Helm or other orchestrators) without touching the config file. GUARDAI_API_KEY_<NAME>=<key> registers a key whose identity is <name> lowercased with underscores turned into hyphens. Companion variables bind extra attributes to that key:

Session

The sealed backend (default) stores session state in an AES-256-GCM encrypted blob returned to the client, so it is stateless and already works across replicas with no shared session store (a multi-replica deployment still needs revocation_backend: redis). The memory backend stores sessions server-side in an in-process HashMap, suitable for development and single-instance testing (sessions are lost on restart and are not shared across replicas). The redis backend stores each session encrypted at rest in a shared Redis (AES-256-GCM under the same key ring as sealed), giving cross-replica, server-side sessions the client references by session_id. It requires session.redis_url, replay_backend: redis, and revocation_backend: redis; Redis holds only ciphertext plus non-PII routing metadata (tenant, policy, and session ids, timestamps, language), never the raw token map. managed is planned.

A session has two independent retention windows. session.ttl_seconds is the idle window, refreshed on every continuation. session.max_lifetime_seconds is the absolute window, anchored at the session's first creation and never extended: once a session is older than this, the next continuation is refused even if the idle window is still open. The default 0 disables the absolute cap, so behavior is unchanged unless you set it. Enable it in production to bound how long an actively continued session can keep its token map alive. When you first enable it, a session sealed by an earlier build carries no clamped absolute deadline, so it can outlive the cap by at most one idle window; it converges on its first continuation under the new build.

Key rotation (session.keyring)

With no keyring, a single sealing key is derived from GUARDAI_SESSION_SECRET. To rotate the sealing secret without invalidating live sessions, declare a keyring: new sessions seal under current_kid, while any listed key can still decrypt. Rotate by adding a new key, switching current_kid, and dropping the old key after one session TTL.

session:
  keyring:
    current_kid: 2
    keys:
      - { kid: 1, secret: "previous-secret-at-least-16-chars" }
      - { kid: 2, secret: "current-secret-at-least-16-chars" }

The ring fails closed at startup on an empty keys, a duplicate kid, a current_kid not present in the ring, or a secret shorter than the derivation minimum.

Detector

Degraded mode: both vs advanced on a NER outage

Both both and advanced run the built-in Rust regex detectors alongside the Python NER sidecar. They differ only in what happens when the sidecar is unreachable or times out:

• both (graceful fallback): the request continues with builtin regex only. The NER-only entity types (person, company, location) are simply not detected for that request. No crash, no error. The transform response reports the actual result on its detector_mode and warnings fields, so a caller can see that NER did not run.
• advanced (fail-closed): NER is required, so a sidecar outage fails the request closed with GUARDAI_DETECTION_UNAVAILABLE (503, retriable) rather than silently returning regex-only results. Choose advanced when passing input through undetected is worse than rejecting it.

Independently of the configured mode, a policy that lists a type under detection.required_for fails a request closed when NER did not actually run for it, so a mandatory type is never dropped by a silent fallback. GET /v1/health reports the CONFIGURED mode, not live NER reachability (so liveness/readiness probes stay stable). Read ner_active on GET /v1/capabilities to see whether NER is configured, and the transform response's detector_mode and warnings to see whether NER ran for a given request.

Bring your own or fine-tuned NER model

The NER models are not pinned into the runtime, only the shipped defaults are. The variables below configure NER without a code change. The model-selection variables (NER_BACKEND, GLINER_MODEL, GUARDAI_SPACY_MODELS, NER_BACKEND_STRICT) are set on the Python detector service; the detection-floor variables (GUARDAI_NER_MIN_CONFIDENCE, GUARDAI_NER_MIN_LENGTH, GUARDAI_NER_ACRONYM_ALLOW, GUARDAI_NER_ACRONYM_STOPLIST) are read by the server runtime; and GUARDAI_DETECTOR_API_KEY secures the hop between them:

Because GLINER_MODEL accepts a local path, a fine-tuned model is used by mounting it into the detector container and pointing GLINER_MODEL at it. The pinned defaults exist for reproducible builds; they never prevent an operator from running their own model. Zero-shot detection labels are still driven per policy via detection.ner_labels, so a domain vocabulary needs no model change at all.

Tuning detection for your domain and language (detector.vocab)

The detector ships defaults for ~30 languages and the common PII formats. Extend it for your domain or locale without recompiling via detector.vocab. The overlay is additive: it can only add or strengthen detection, never silently weaken it, and invalid config fails startup.

detector:
  vocab:
    # Context-boost words per entity type (raise confidence when seen near a match).
    context_words:
      money: ["honorar", "rechnungsbetrag"]
      person: ["mandant", "ansprechpartner"]
    # Currency markers beyond ISO 4217 (each 2-8 uppercase ASCII alphanumerics).
    currency_codes: ["XBT"]
    # Extend ANY entity type with locale/domain regexes. A built-in label (address,
    # date_of_birth, ...) yields the built-in entity; use "custom:<name>" for a new type.
    extra_patterns:
      address: ['〒\d{3}-\d{4}[^\n]{0,40}']          # Japanese postal address
      date_of_birth: ['\b\d{4}年\d{1,2}月\d{1,2}日\b']  # Japanese date
      "custom:vat_id": ['\bVAT-\d{6}\b']

Narrowing money detection is the only detector.vocab control that reduces detection, so it is a gated break-glass requiring explicit acknowledgement (logged at startup):

detector:
  vocab:
    money_colliding_codes: ["TRY"]
    allow_money_detection_suppression: true
    money_suppression_reason: "TRY collides with the verb 'try' in our corpus"

Per-policy detection (custom regex detectors, required-NER fail-closed, confidence floors) is set in policy YAML via custom_patterns and a detection block. The proxy reads the detection vocabulary overlay from GUARDAI_DETECTOR_VOCAB (JSON). For the end-to-end extension model that ties these overlays to custom entity types and channels, see the extensibility guide.

External HTTP detector (detector.webhook)

Register an external detector over HTTP. Per request the runtime POSTs {text, language} to the endpoint and merges the returned spans additively, so a domain-specific detector augments the built-in and NER detectors. Absent = detection unaffected; invalid config aborts startup.

detector:
  webhook:
    url: https://detector.internal/scan
    entity_types: [employee_id, case_ref]   # only these types are accepted; no built-in shadowing
    api_key: ${DETECTOR_KEY}                 # optional, sent as X-Detector-API-Key
    timeout_secs: 5
    required: false                          # true => a failure (timeout/error/malformed) rejects the request

The plugin can only ADD coverage: a span overlapping a built-in or NER span is dropped, and an offset that disagrees with a returned value is rejected. See the plugin guide for the full contract.

Chunk detection concurrency (rag.chunk_detection_concurrency)

During RAG ingest, per-chunk detection runs concurrently up to this bound (0 = host CPU count, maximum 256). Tokenization stays ordered, so output is identical regardless of the value.

Ingest wall-clock budget (rag.max_ingest_duration_secs)

Each document ingest (/v1/rag/ingest and every item of /v1/rag/ingest/batch, independently) is bounded by a per-document wall-clock budget. Past it the ingest is refused 503 GUARDAI_DEADLINE_EXCEEDED with nothing sealed and any in-flight detection cancelled, so a pathological document cannot pin a request unbounded. The budget is finite and secure by default: 3600 seconds (one hour), tunable from 1 to 86400 (24 hours), with no off switch. A batch item's budget is independent, so one slow document never consumes another's. A request carrying an Idempotency-Key is also bounded by the shorter idempotency operation deadline. A trip is load dependent (the same document can pass on an idle server), so the response is a retriable 503, and any ingest that finishes within the budget behaves exactly as before.

Notifications (notifications)

Deliver the runtime's PII-free audit events to an external endpoint (a SIEM or observability pipeline). Delivery is fire-and-forget and fail-open, so a slow or down endpoint never blocks or fails a request. A notification is enqueued only after its audit event is recorded, so on the non-dev default trail (durable file backend with audit.strict, enforced at startup unless waived) a delivered notification implies a durable audit record; under audit.allow_ephemeral or dev mode the trail is not durable, so delivery is best-effort and does not imply a persisted record. The payload carries entity types and counts, never values, with session id, trace id, and tenant id as one-way fingerprints. Absent = disabled.

notifications:
  webhook_url: https://sink.internal/guardai-events
  api_key: ${SINK_KEY}                       # optional, sent as X-Notification-Key
  timeout_secs: 5
  events: [transform, policy_denied, session_expired]   # empty => all events

Language packs

Language enrichment (gender, honorifics, formality) is fully data-driven: every language ships a built-in JSON lexicon (the immutable floor), and operators add, extend, or override any language from data, with no source change, via the Python detector's GUARDAI_LANGUAGE_PACKS (a JSON file mapping a language code to a lexicon). Each entry's optional _mode selects the operation:

{
  "yue": { "female_titles": ["女士"], "male_titles": ["先生"] },
  "de":  { "male_names": ["acmebob"], "informal_markers": ["servus "] },
  "fr":  { "_mode": "replace", "female_titles": ["Mme "], "male_titles": ["M. "] }
}

• add a brand-new language (no built-in for the code): registered as-is.
• extend a built-in (default, _mode absent or "extend"): the overlay can only widen the built-in. The built-in's gender/honorific stay authoritative (the overlay only fills gaps for inputs the built-in cannot classify), so an extend overlay can never flip a built-in confident result; new formality markers join the built-in's vote; structural fields (rtl, name_order) stay built-in.
• replace a built-in (_mode: "replace"): full override.

A malformed pack fails loudly at startup. Lexicon fields: female_titles, male_titles, female_names, male_names, formal_markers, informal_markers, honorific_suffixes ([suffix, label] pairs), patronymic_suffixes ({ "female": [...], "male": [...] }), rtl, name_order ("given_first" | "given_last"), and default_formality.

Policy

Policy integrity (policy.integrity)

Optional signed-manifest verification of the policy directory. It is fail-closed and both-or-neither: when both manifest and secret are set, the server verifies every policy file against the signed manifest at startup and refuses to start on any mismatch. Both absent disables it; setting exactly one is a config error (a security control is not half-enabled).

policy:
  integrity:
    manifest: /etc/guardai/policies/.signatures.json  # relpath -> HMAC map from `oguardai-server policy sign-dir`
    secret: "${GUARDAI_POLICY_SIGNING_KEY}"            # HMAC signing secret (min 16 chars)
    kid: "policy-signer-1"                             # optional key id (informational)

Transform

Output Protection

When an output NER scanner is installed (detector.mode both/advanced, or GUARDAI_OUTPUT_SCAN_NER=1 on the proxy), the output guard now also runs NER over decoded views, so a person, company, or location the model emits base64- or percent-encoded is masked exactly as its plaintext form would be. This is on by default whenever the scanner is installed; the two knobs above add an independent posture on the encoding shape itself. With no scanner installed and both knobs at allow, encoded output forwards exactly as before.

output_protection.enabled is a production invariant: with auth.mode other than dev, the server refuses to start when it is false (use auth.mode=dev to bypass for testing).

The output guard runs the built-in regex detectors on every response. The model only ever sees tokens, so a real-looking name it emits is generated and structured-only regex would miss it. The NER-capable modes both and advanced add a NER pass on output unless you set detector.scan_output_with_ner: false; under builtin there is no such pass. It runs additively over the regex floor (only adds detections, never suppresses one). Because output scanning is an explicit safety net, it fails closed: a NER-sidecar outage blocks the response rather than silently degrading to regex-only (independent of the ingress mode). The proxy enables the same pass with GUARDAI_OUTPUT_SCAN_NER=1, covering both plain-text output and structured JSON response field values (object keys stay regex-only, since per-key NER multiplies sidecar calls for little gain).

Restore Templates

Localized restore output (honorifics, abstract labels) merged over the built-in defaults for ~30 languages. Override only what you need; everything else keeps its default.

restore_templates:
  person_titles:
    de:
      formal_female: "Sehr geehrte Frau {name}"
      formal_male: "Sehr geehrter Herr {name}"
    tr:
      formal_female: "Sayın {name}"
  company_abstract_labels:
    ja: "（会社名）"

The proxy reads the same overrides from GUARDAI_RESTORE_TEMPLATES (JSON).

Restore strategies (partial reveal)

A partial restore reveals a bounded, deterministic fragment of a value instead of the full original. You configure it per entity type under restore_templates.partial_formats (deployment-wide) or per policy under restore_strategies (same shape, policy-scoped). Each entry is keyed by the entity type name, for example credit_card or salary.

restore_templates:
  partial_formats:
    # Reveal only the last n characters, mask the rest.
    credit_card:
      kind: reveal_last_n
      n: 4
      mask_char: "*"
    # Always mask, never reveal.
    ssn:
      kind: mask
    # Generalize a numeric value into a labelled band (e.g. salary bands).
    salary:
      kind: bucket
      ranges:
        - { max: 50000, label: "<50k" }
        - { max: 100000, label: "50k-100k" }
        - { label: "100k+" }   # open-ended top band: omit max

The same per-policy form lives in policy YAML:

restore_strategies:
  credit_card:
    kind: reveal_last_n
    n: 4
    mask_char: "*"

Five kinds are available:

Use restore_strategies in a policy when the format should be scoped to that policy, and restore_templates.partial_formats when the format should apply deployment-wide across policies.

These rules hold:

• Channel-ceiling gated. A partial format applies only when the channel-resolved restore mode is Partial. It never widens what the channel allows: if the channel ceiling is Masked or stricter, the value stays masked regardless of the format.
• Fail closed. If a strategy cannot produce a bounded result, it masks. reveal_last_n masks the whole value when the value is no longer than n. bucket masks when the value does not parse as a number or no range matches.
• Invalid config aborts startup. A reveal_last_n with n outside 1..64, an empty bucket ranges, or a missing required field is rejected at load time, so a misconfigured format cannot silently reveal more than intended.

For the broader extension model (custom entity types, caller-role conditions, custom output channels, detector and language overlays), see the extensibility guide.

Prompt Security

The built-in injection patterns are an immutable floor: English plus a baseline for the canonical attacks (instruction override, system-prompt extraction) in German, French, Spanish, Italian, Portuguese, and Dutch. Config can only add, never remove them. Extend detection to any other language or house style with extra_patterns (each a Rust regex; set case-insensitivity inline with (?i)); an entry that fails to compile is skipped with an error log so the floor still applies.

prompt_security:
  action: strip
  extra_patterns:
    - pattern: '(?i)önceki\s+talimat.{0,20}(?:yok\s*say|unut)'   # Turkish instruction override
      label: "instruction_override (tr)"

File Upload

Request Limits

Operational request limits, each bounded by a built-in maximum. The batch and streaming caps default to their maximum, so they are tighten-only (a DoS ceiling you can only lower). The heavy-op knobs default below their maximum, so they are tunable to your workload up to a built-in safety maximum. A value above its maximum, or zero, aborts startup, so a misconfiguration can never weaken the bound.

PDF text extraction runs in a short-lived child process under a hard RLIMIT_AS address-space cap and a wall-clock timeout, so a decompression-bomb PDF (a small file whose compressed streams inflate to gigabytes) exhausts the bounded child and is rejected with a clean error instead of exhausting the server. Both limits are security ceilings: a deployment may only lower them, and a value above the maximum or zero aborts startup. The raw PDF never leaves the runtime: the sandbox child is a re-exec of the server binary, not an external service.

The address-space cap is a hard fail-closed extraction ceiling. A genuinely large or structurally complex PDF whose extraction would need more than the cap is rejected rather than risk the server, so a small fraction of legitimate documents may be refused. This is deliberate: raising the ceiling above the built-in maximum requires a code change, since config may only lower it.

Rate Limiting

Behind reverse proxies, set trusted_proxy_cidrs to the proxy address range. Every proxy tier in front of the server must append the address it received the request from (the standard nginx proxy_add_x_forwarded_for and ALB behavior), and every intermediate proxy address must be inside trusted_proxy_cidrs, not just the first hop. The walk believes an entry only while its writer is trusted, treats the first untrusted entry as the client, fails closed to the innermost trusted proxy on a broken chain, and ignores the header entirely when the TCP peer is not in the list.

Tenants

Per-tenant overrides allow different policies and rate limits per tenant:

tenants:
  acme-corp:
    default_policy: gdpr-strict
    allowed_policies:
      - gdpr-strict
      - healthcare
    rate_limit:
      requests_per_second: 50
      burst_size: 100

• allowed_policies: Optional allowlist of policy names this tenant may use. When set, request-level policy overrides are validated against this list. If absent or empty, all loaded policies are permitted.
• Unknown tenants fall through to global defaults.
• A misspelled key inside a tenant entry aborts startup, it is not ignored. For example allowed_polcies (a typo of allowed_policies) fails the load rather than leaving the allowlist unset, which would otherwise permit every loaded policy.

RAG access control

The RAG access-control lattice (used to filter document chunks by access_level vs each chunk's classification) defaults to public < internal < confidential < restricted. Override it for your domain scheme without code:

rag:
  classification_levels: ["unclassified", "cui", "confidential", "secret", "top_secret"]

Levels are ordered least to most restrictive. An access level grants a chunk when its rank is greater than or equal to the chunk's. Any label not in the lattice ranks most-restrictive (fail closed), so an unknown or misspelled classification is never over-exposed. The list must be non-empty, unique, and at most 255 entries.

Providers

Per-provider behavior profiles. Each key is a provider name, and its context_strategy sets how much entity context metadata that provider receives. Built-in defaults exist for openai, anthropic, and local; the reserved key default sets the profile used for any provider without an explicit entry. When the providers map is omitted, the built-in defaults apply.

providers:
  openai:
    name: openai
    context_strategy: full
  anthropic:
    name: anthropic
    context_strategy: type_summary
  local:
    name: local
    context_strategy: referenced_only
  default:
    name: default
    context_strategy: full

These profiles govern the server data path, and only while transform.context_strategy keeps its full default. On that default, a request that names a provider in its context.provider field receives that provider's context_strategy from this table, and a named provider with no entry falls to the default profile. Setting transform.context_strategy to any value other than full makes the server apply that one value to every request and ignore this table. A request that names no provider uses the transform.context_strategy value.

The proxy does not consult these profiles. It carries no per-request provider context and forces context_strategy: none on every egress by design, so a provider reached through the proxy receives no entity context metadata regardless of the values above.

Audit

Where audit events are written. Every data-path request produces an audit event with no detected values. The protected durable file can retain operator labels such as tenant and policy identifiers; logs and outbound copies fingerprint those free-form fields.

audit:
  backend: file
  file:
    path: /var/log/guardai/audit.log
  queue_capacity: 8192
  strict: true
  strict_ack_timeout_secs: 30
  shutdown_timeout_secs: 60

The live leaf must be a regular file owned by the runtime user, have one link, and end at exact mode 0600. The runtime creates new leaves privately and can narrow a strict permission superset to 0600 without changing the contents. It rejects symlinks, non-regular files, hard-linked live files, wrong ownership, and incompatible modes. Keep the parent directory stable, private, and under the same administrative control as the service.

The runtime also qualifies the opened filesystem for durability. The default accepts any non-volatile filesystem: the certified set (ext4, XFS, Btrfs, and APFS on macOS) is accepted silently, while remote families (NFS and EFS, SMB and CIFS including Azure Files, 9p, Ceph) and unverified families (FUSE, overlayfs, and any unknown filesystem) are accepted with a startup warning naming the fsync and locking caveat. Memory-backed filesystems (tmpfs, ramfs, hugetlbfs) are always refused for the active log and exports. Set audit.require_certified_filesystem: true (or GUARDAI_PROXY_AUDIT_REQUIRE_CERTIFIED_FS on the proxy) to restore the strict allowlist that also refuses non-local, asynchronous, union, or unknown-permission mounts. A container image layer is normally overlayfs, which now works with a warning; mount a dedicated volume at the audit directory anyway because container-layer contents do not outlive the container. A Kubernetes PVC works whenever its storage class presents a durable filesystem, with a block storage class recommended for the strongest guarantees.

Offline verification and export accept only owned, regular source files at mode 0400 or 0600. Unsafe sources are rejected without mutation. See Verifying audit-log integrity for descriptor binding, archive keys, and export-output handling.

A non-dev start (auth.mode of api_key, jwt, or oidc) requires a durable, strict trail: audit.backend: file AND audit.strict: true. Startup fails otherwise, so a successful request can never have its audit record silently dropped. Set audit.allow_ephemeral: true (or GUARDAI_ALLOW_EPHEMERAL_AUDIT=1) to explicitly accept an ephemeral or non-strict trail. The compliance preset ignores this waiver and always forces durable, strict.

To pin both at once, start the server with the --compliance flag or GUARDAI_COMPLIANCE=1. The compliance preset only tightens: it forces audit.backend: file and audit.strict: true, and it fails closed at startup if the resulting audit trail is not both durable and strict (for example when audit.file.path is unset). It also floors detect.include_values_default to false when the operator has not set it. The gate runs regardless of auth.mode, so it holds even in dev mode. The audit event schema additionally reserves optional GDPR Art. 30 labels (purpose, legal_basis, data_category), PII-free controlled labels a deployment may populate from policy/config; see the compliance controls page.

Graceful shutdown

The service owns bounded shutdown phases, but its supervisor must allow the cumulative envelope. With strict file audit defaults, the envelope is 180 seconds: 30 seconds for HTTP drain, 75 seconds for request quiescence, 60 seconds for audit finalization, and a 15-second safety margin. The shipped Helm, Compose, and systemd definitions allow that full interval.

If you raise any shutdown or strict acknowledgement budget in a custom deployment, raise the supervisor grace period by the same cumulative amount. A shorter Kubernetes grace, Compose stop_grace_period, or systemd TimeoutStopSec can terminate the process before audit custody is released.

Revocation and Replay backends

Two top-level backends control session revocation and request-replay protection. Both default to memory and can be switched to redis for a shared store across replicas. A redis backend requires session.redis_url (or GUARDAI_REDIS_URL) and fails startup validation without it.

When running more than one replica, use redis for both so a revoked session and a replayed session_state are recognized on every instance. Redis stores only HMAC digests, never raw PII.

revocation_backend: redis
replay_backend: redis
session:
  redis_url: "redis://redis:6379"

Idempotency

Mutating, non-streaming routes (transform, batch transform, RAG ingest/delete, revoke, session delete) accept an Idempotency-Key header so a client can safely retry without executing the mutation twice. The store is configured under idempotency:

idempotency:
  backend: memory
  ttl_seconds: 86400
  in_progress_ttl_seconds: 450

Environment Variables

Environment variables override configuration file values.

GLINER_LABELS and GLINER_LABEL_MAP set the deployment-wide default label set, and their targets must be built-in entity types: the detector advertises its static emit set over GET /labels at startup, and a runtime that cannot resolve an advertised target refuses to start when NER is required (it warns and falls back to request-time validation when NER is optional). Domain-specific custom types belong in a policy's detection.ner_labels / detection.ner_label_map (additive, fail-closed), not in the deployment-wide map; see the policy authoring guide.

detection.required_for fails a request closed when the required NER backend is unavailable or degraded, and the Rust-side confidence floors exempt required types after detection. It does not override the GLiNER model boundary above: a span the model scores below GLINER_CONFIDENCE_THRESHOLD is never delivered to the policy. A high-recall deployment lowers that threshold.

GUARDAI_SESSION_SECRET

This is the only required environment variable. A non-dev server requires at least 32 characters (dev tolerates the shorter default); it is used for AES-256-GCM encryption of session state blobs. Generate a strong one with openssl rand -base64 32. All server instances in an HA deployment must share the same secret.

# Generate a suitable secret
openssl rand -base64 32

RUST_LOG

Controls log verbosity using the tracing filter syntax. Left unset, the server applies warn,oguardai_server=info,guardai_server=info,guardai::audit=info,tower_http=info. Setting RUST_LOG replaces that filter outright, so keep three things in whatever you set. The bare warn floor and the oguardai_server target (the binary, distinct from the guardai_server library) carry the startup report and the output guard's own block reasons, and a filter naming only guardai_server mutes both, leaving refused requests with no server-side explanation. guardai::audit=info is what lets the audit trail past that floor: the default log audit backend emits every event at INFO on that target, so a filter without the directive leaves the deployment with no audit trail at all. The durable file backend writes regardless of the log filter.

# The default, with session handling turned up to debug
RUST_LOG=warn,oguardai_server=info,guardai_server=info,guardai::audit=info,tower_http=info,guardai_session=debug

# Trace everything (very verbose, development only)
RUST_LOG=trace

# Quieter: keep the warn floor, the startup and guard diagnostics and the audit trail, drop request logging
RUST_LOG=warn,oguardai_server=info,guardai_server=info,guardai::audit=info

Example: Minimal Production Config

server:
  host: "0.0.0.0"
  port: 3000
session:
  backend: sealed
  ttl_seconds: 3600
policy:
  default: default
  directory: /etc/guardai/policies
auth:
  mode: api_key            # requires at least one API key (env or auth.api_keys)
audit:
  backend: file            # non-dev requires the durable, strict trail
  strict: true
  file:
    path: /var/log/guardai/audit.log
detector:
  advanced_url: ""

GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)
GUARDAI_API_KEY_1=$(openssl rand -hex 32)
RUST_LOG=warn,oguardai_server=info,guardai_server=info,guardai::audit=info,tower_http=info

Example: Full Stack with NER

server:
  host: "0.0.0.0"
  port: 3000
session:
  backend: sealed
  ttl_seconds: 7200
policy:
  default: default
  directory: /etc/guardai/policies
auth:
  mode: api_key            # requires at least one API key (env or auth.api_keys)
audit:
  backend: file            # non-dev requires the durable, strict trail
  strict: true
  file:
    path: /var/log/guardai/audit.log
transform:
  context_strategy: full
  max_context_tokens: 4096
detector:
  advanced_url: http://detector:9090

GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)
GUARDAI_API_KEY_1=$(openssl rand -hex 32)
GUARDAI_DETECTOR_API_KEY=$(openssl rand -hex 32)   # same value on the detector service
RUST_LOG=warn,oguardai_server=info,guardai_server=info,guardai::audit=info,tower_http=info

Note: For a shared server-side session store across replicas, set session.backend: redis with GUARDAI_REDIS_URL plus replay_backend: redis and revocation_backend: redis. A redis session or replay backend advertises a multi-replica topology, so startup fails closed unless revocation is the shared (redis) authority too. Each session is encrypted at rest (AES-256-GCM). The default sealed backend is stateless and also works for HA, but a multi-replica sealed deployment still needs revocation_backend: redis (advertise it with high_availability: true).