cyoda configuration reference

cyoda-go version 0.8.4

config

NAME

config — environment-driven configuration for cyoda.

SYNOPSIS

All configuration is environment variables prefixed with CYODA_. Topics group related variables:

config.auth — IAM mode, JWT issuer, admin controls
config.cors — CORS middleware mode and allowed origins
config.database — storage backend selection, per-backend connection settings
config.grpc — gRPC listener and compute-node credentials
config.schema — schema-extension log tuning
config.cluster — multi-node clustering, gossip, cross-node dispatch
config.scheduler — scheduled-transition scan-loop cadence, distribution, and expiry grace
config all — flat listing of every variable (append --format=json for the docs-site JSON)

DESCRIPTION

Precedence

Environment variables beat default values. The _FILE suffix variant takes precedence over the plain variable when both are set — for example, CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url wins over CYODA_POSTGRES_URL. There are no command-line flags for configuration values; env vars are the sole configuration surface.

_FILE suffix support

The following variables support the _FILE suffix. Setting CYODA_FOO_FILE=<path> causes the binary to read the value from the file at <path>, trimming trailing whitespace. The _FILE variant takes precedence over CYODA_FOO when both are set. A set but unreadable _FILE path causes immediate startup failure.

CYODA_JWT_SIGNING_KEY / CYODA_JWT_SIGNING_KEY_FILE
CYODA_HMAC_SECRET / CYODA_HMAC_SECRET_FILE
CYODA_BOOTSTRAP_CLIENT_SECRET / CYODA_BOOTSTRAP_CLIENT_SECRET_FILE
CYODA_METRICS_BEARER / CYODA_METRICS_BEARER_FILE

Profile loader

CYODA_PROFILES is a comma-separated list of profile names. For each name N, a file cyoda.N.env is loaded from the working directory before the process’s own environment is consulted. This supports local development without exporting many variables.

Example:

CYODA_PROFILES=postgres,otel go run ./cmd/cyoda

loads cyoda.postgres.env and cyoda.otel.env from the working directory.

Server options

CYODA_HTTP_PORT (int, default: 8080) — HTTP listen port.
CYODA_HTTP_READ_HEADER_TIMEOUT (duration, default: 10s) — time allowed to receive a request’s headers on the API and admin servers. 0 falls back to CYODA_HTTP_READ_TIMEOUT.
CYODA_HTTP_READ_TIMEOUT (duration, default: 5m) — time allowed to receive a whole request, body included. Does not limit handler execution. 0 disables.
CYODA_HTTP_WRITE_TIMEOUT (duration, default: 0s) — time from the end of the request headers to the end of the response. Limits handler execution, so it ships disabled; set only if you want the server to cut off long-running requests.
CYODA_HTTP_IDLE_TIMEOUT (duration, default: 2m) — how long an idle keep-alive connection is held open between requests. 0 falls back to CYODA_HTTP_READ_TIMEOUT.
CYODA_CONTEXT_PATH (string, default: /api) — URL prefix for all routes.
CYODA_ERROR_RESPONSE_MODE (string, default: sanitized) — error detail level: sanitized (generic message + ticket UUID for 5xx) or verbose (internal error detail included in responses; development use only).
CYODA_LOG_LEVEL (string, default: info) — accepted: debug|info|warn|error.
CYODA_SUPPRESS_BANNER (bool, default: false) — silence startup and mock-auth banners.
CYODA_STARTUP_TIMEOUT (duration, default: 30s) — deadline for plugin init, TM init, and (cluster mode) the gossip seed-join retry loop.
CYODA_DEBUG — reserved; not currently read by the server.
CYODA_MAX_STATE_VISITS (int, default: 10) — max visits per state in workflow cascade.
CYODA_MODEL_CACHE_LEASE (duration, default: 5m) — model cache lease duration; actual expiry is jittered ±10%.
CYODA_STATS_GROUP_MAX (int, default: 10000) — cardinality ceiling for POST /api/entity/stats/{entityName}/{modelVersion}/query. When the grouped-stats result produces more distinct groupKey combinations than this value, the request fails with 422 GROUP_CARDINALITY_EXCEEDED. Also caps the request limit parameter (limit > max rejects with 400 INVALID_LIMIT). Values <= 0 are silently clamped to the default (10000) — a non-positive cap would disable the ceiling entirely (plugins treat <= 0 as “unbounded”), defeating the safety net.

Admin and metrics

CYODA_ADMIN_PORT (int, default: 9091) — admin port for health and metrics.
CYODA_ADMIN_BIND_ADDRESS (string, default: 127.0.0.1) — admin listener bind address.
CYODA_METRICS_REQUIRE_AUTH (bool, default: false) — require Bearer auth on /metrics; startup fails if true and CYODA_METRICS_BEARER is empty.
CYODA_METRICS_BEARER (string, default: unset) — static Bearer token for GET /metrics. Supports _FILE suffix.
CYODA_OTEL_ENABLED (bool, default: false) — enable OpenTelemetry tracing and metrics.

Search internals

CYODA_SEARCH_SNAPSHOT_TTL (duration, default: 1h) — search snapshot TTL.
CYODA_SEARCH_REAP_INTERVAL (duration, default: 5m) — search snapshot reap interval: how often terminal jobs older than CYODA_SEARCH_SNAPSHOT_TTL are deleted. It no longer drives the stale/reclaim sweep — that runs on CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL’s ticker instead (see CYODA_SEARCH_JOB_STALE_AFTER). This is purely the snapshot-cleanup cadence.
CYODA_SEARCH_MAX_SORT_KEYS (int, default: 16) — maximum number of sort keys per search request. Requests exceeding this cap are rejected with 400 INVALID_FIELD_PATH. Values <= 0 are clamped to the default.
CYODA_SEARCH_ASYNC_WORKERS (int, default: 8) — async-search worker pool size. Config is a QA’d artefact: values < 1 fail startup rather than being clamped.
CYODA_SEARCH_ASYNC_QUEUE (int, default: 256) — async-search submit queue capacity beyond the running workers. Once both are exhausted, submission fails with 503 SEARCH_QUEUE_FULL (retryable). Values < 0 fail startup.
CYODA_SEARCH_ASYNC_MAX_PER_TENANT (int, default: 8 — tracks CYODA_SEARCH_ASYNC_WORKERS) — maximum async-search jobs one tenant may have in flight (queued or running) on a node. Over-cap submissions get the same retryable 503 SEARCH_QUEUE_FULL, so one tenant’s burst cannot fill the shared queue and lock every other tenant out. A tenant may still occupy every worker; it just cannot hold more than this many queue slots. 0 disables the cap. Values < 0 fail startup.
CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL (duration, default: 15s) — how often a running async-search executor stamps job liveness and polls for a cross-node cancel/terminal status, starting at submit time (queued or scanning). Config is a QA’d artefact: values <= 0 fail startup rather than being clamped.
CYODA_SEARCH_JOB_STALE_AFTER (duration, default: 5m) — how long a RUNNING async-search job may go without a heartbeat before the reaper claims it for reclaim (its owning executor most likely crashed or was killed). Config is a QA’d artefact: values below 4 x CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL fail startup rather than being clamped. The stale/reclaim sweep runs on CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL’s ticker (default 15s) plus once at startup — not on CYODA_SEARCH_REAP_INTERVAL, which now drives only the snapshot-TTL reap. A crash therefore hands off within CYODA_SEARCH_JOB_STALE_AFTER + one heartbeat interval (~5m15s at defaults); a graceful shutdown or restart releases in-flight jobs immediately, so those hand off within one heartbeat interval — or immediately on the restarted node’s own startup sweep. Operational note: on postgres, a node that dies mid-save (inside the SaveResults chunk transaction) is reaped by the server’s transaction-local idle timeout rather than by this sweep directly, so a mid-save crash’s handoff still matches any other crash once that timeout releases the row.
CYODA_SEARCH_JOB_MAX_ATTEMPTS (int, default: 3) — executions an async-search job may consume before it is failed: the initial run plus one per executor lost without a graceful release. A graceful handoff (release then reclaim) does not count. Config is a QA’d artefact: values < 1 fail startup rather than being clamped. 1 disables re-execution — a job is failed the first time its executor is lost.

Cluster and dispatch

See config.cluster for multi-node clustering, gossip, and cross-node dispatch variables.

Subtopics

cyoda help config auth — config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.
cyoda help config cluster — - CYODA_CLUSTER_ENABLED (bool, default: false) — enable multi-node clustering.
CYODA_NODE_ID (string, default: unset) — unique node identifier; required when CYODA_CLUSTER_ENABLED=true; any non-empty string is accepted.
CYODA_NODE_ADDR (string, default: http://localhost:8080) — this node’s HTTP base URL; must include scheme (http:// or https://).
CYODA_GRPC_NODE_ADDR (string, default: unset) — this node’s gRPC endpoint advertised to peers (host:port, no scheme). When set, peers dial this address for cross-node gRPC callback forwarding. When unset, peers derive the gRPC address from this node’s HTTP host plus their own CYODA_GRPC_PORT (uniform-deployment default).
CYODA_GOSSIP_ADDR (string, default: :7946) — gossip protocol listen address; format [host]:port — parsed via net.SplitHostPort; invalid format causes startup failure.
CYODA_GOSSIP_STABILITY_WINDOW (duration, default: 2s) — gossip stability window.
CYODA_SEED_NODES (string, default: empty) — comma-separated list of seed node addresses (e.g., node1.example.com:7946,node2.example.com:7946); empty means single-node or seed-discovery handled externally.
CYODA_HMAC_SECRET (string, default: unset) — hex-encoded HMAC secret for inter-node dispatch authentication; required when CYODA_CLUSTER_ENABLED=true. Supports _FILE suffix. Single root secret for gossip encryption, dispatch AEAD, and tx-token signing; no versioned-key rotation — changing it requires a full-cluster stop/start (see the cluster help topic, SECRET ROTATION).
CYODA_PROXY_TIMEOUT (duration, default: 30s) — request proxy timeout.
CYODA_DISPATCH_WAIT_TIMEOUT (duration, default: 5s) — how long the dispatcher polls gossip for a compute member with matching tags.
CYODA_DISPATCH_FORWARD_TIMEOUT (duration, default: 30s) — HTTP timeout for the cross-node forwarding call.
CYODA_TX_TOKEN_TTL (duration, default: 90s) — TTL of the signed transaction routing token minted on processor/criteria dispatch; must be ≥ CYODA_DISPATCH_FORWARD_TIMEOUT so the token remains valid through the full round-trip and callback verification, including the forwarded-chain case where two budgets stack.
cyoda help config cors — config.cors — Cross-Origin Resource Sharing (CORS) controls for the public HTTP surface.
cyoda help config database — config.database — storage backend selection and per-backend connection settings.
cyoda help config grpc — config.grpc — gRPC listener settings and compute-node credentials.
cyoda help config scheduler — - CYODA_SCHEDULER_ENABLED (bool, default: true) — kill switch for the coordinator scan loop.
CYODA_SCHEDULER_SCAN_INTERVAL (duration, default: 1s) — coordinator scan cadence.
CYODA_SCHEDULER_BATCH_SIZE (int, default: 100) — max due tasks pulled per scan.
CYODA_SCHEDULER_DISTRIBUTION (string, default: round-robin) — dispatch-target selection strategy: round-robin or self. Forced to self whenever CYODA_CLUSTER_ENABLED=false.
CYODA_SCHEDULER_COORDINATOR (string, default: lowest-node-id) — coordinator-election strategy; the member with the lexicographically smallest node ID scans on each tick.
CYODA_SCHEDULER_REDISPATCH_BACKOFF (duration, default: 30s) — best-effort re-dispatch throttle window applied to a task once it is picked up, so the same due task isn’t immediately re-dispatched on the next scan.
CYODA_SCHEDULER_EXPIRY_GRACE (duration, default: 100ms) — grace band above a scheduled transition’s timeoutMs before it is expired instead of fired late; size to at least the maximum expected inter-node clock skew.
cyoda help config schema — config.schema — schema-extension log tuning.

Raw formats

/help/config.json — full descriptor (matches GET /help/{topic} envelope)
/help/config.md — body only