Configuration

cyoda-go reads configuration from CYODA_* environment variables and from .env-format files. The model — how sources compose, how profiles work, and how secrets are mounted from files — is described below, and the authoritative key list (every variable, its type, its default) is mirrored in full under All variables. The binary remains the source of truth: run cyoda help config to read it directly.

Sources and precedence

Values resolve in this order, highest to lowest:

Shell environment
.env.{profile} files (in CYODA_PROFILES declaration order; later profiles override earlier ones within their group)
.env in the project directory
User config file
System config file
Hardcoded defaults

Format is .env only (godotenv-parsed). No TOML, no YAML, no --config flag. Subcommand flags (e.g. cyoda init --force) are operation-scoped and do not override server-runtime configuration.

User config path varies by OS: ~/.config/cyoda/cyoda.env (Linux, macOS with XDG), %AppData%\cyoda\cyoda.env (Windows). System config lives at /etc/cyoda/cyoda.env on POSIX.

Profiles

CYODA_PROFILES is comma-separated and evaluated in declaration order. Within a profile, regular .env precedence applies; across profiles, later entries in the list override earlier ones.

Secrets via `_FILE` suffix

Any variable that accepts a credential (Postgres URL, JWT signing key, metrics bearer, gossip HMAC, bootstrap client secret) accepts a companion *_FILE variable that reads from a mounted file. Trailing whitespace is stripped. The _FILE variant takes precedence when both are set — the pattern designed for Kubernetes Secrets and Docker secrets mounts.

All variables

Every CYODA_* variable the engine reads, grouped by topic. Empty Default or Type cells mean the binary reports none. This table is generated from the pinned cyoda-go configuration surface.

admin (5)

Variable	Type	Default	Description
`CYODA_ADMIN_BIND_ADDRESS`	string	`127.0.0.1`	Admin listener bind address.
`CYODA_ADMIN_PORT`	int	`9091`	Admin port for health and metrics.
`CYODA_METRICS_BEARER`	string	—	Static Bearer token for GET /metrics. Supports _FILE suffix.
`CYODA_METRICS_REQUIRE_AUTH`	bool	`false`	Require Bearer auth on /metrics; startup fails if true and CYODA_METRICS_BEARER is empty.
`CYODA_OTEL_ENABLED`	bool	`false`	Enable OpenTelemetry tracing and metrics.

auth (27)

Variable	Type	Default	Description
`CYODA_AUTH_CACHE_RECONCILE_INTERVAL`	duration	`1m`	Periodic KV-reconcile interval for the trusted-key and OIDC-provider caches; jittered ±10%; verification fails closed after 10× this without a successful reconcile.
`CYODA_BOOTSTRAP_CLIENT_ID`	string	—	Bootstrap M2M client ID.
`CYODA_BOOTSTRAP_CLIENT_SECRET`	string	—	Bootstrap M2M client secret; must be set when CYODA_BOOTSTRAP_CLIENT_ID is set. Supports _FILE suffix.
`CYODA_BOOTSTRAP_ROLES`	csv	`ROLE_ADMIN,ROLE_M2M`	Comma-separated roles granted to the bootstrap client.
`CYODA_BOOTSTRAP_TENANT_ID`	string	`default-tenant`	Tenant for the bootstrap client.
`CYODA_BOOTSTRAP_USER_ID`	string	`admin`	User ID for the bootstrap client.
`CYODA_IAM_KEYPAIR_DEFAULT_VALIDITY_DAYS`	int	`365`	Default validity for the bootstrap signing key and runtime-issued keypairs.
`CYODA_IAM_M2M_ADMIN_ROLE_ENABLED`	bool	`false`	Gates the withAdminRole=true query parameter on POST /clients.
`CYODA_IAM_MOCK_KIND`	string	`user`	Principal kind (user\|service\|system) assigned to the default UserContext in mock mode.
`CYODA_IAM_MOCK_ROLES`	csv	`ROLE_ADMIN,ROLE_M2M`	Comma-separated default user roles assigned to all requests in mock mode.
`CYODA_IAM_MODE`	string	`mock`	Authentication mode: mock or jwt.
`CYODA_IAM_TRUSTED_KEY_MAX_JWK_PROPERTIES`	int	`20`	Caps the number of properties in a registered JWK.
`CYODA_IAM_TRUSTED_KEY_MAX_PER_TENANT`	int	`10`	Per-tenant cap on registered trusted keys; 0 means unbounded.
`CYODA_IAM_TRUSTED_KEY_MAX_VALIDITY_DAYS`	int	`365`	Default validity for trusted keys when the registration request omits validTo.
`CYODA_IAM_TRUSTED_KEY_REGISTRATION_ENABLED`	bool	`false`	Gates the /oauth/keys/trusted/* endpoints; disabled returns 404 FEATURE_DISABLED.
`CYODA_JWT_AUDIENCE`	string	—	Expected JWT audience (aud); empty disables the audience check.
`CYODA_JWT_BOOTSTRAP_AUDIENCE`	string	`client`	Audience for the bootstrap signing key derived from CYODA_JWT_SIGNING_KEY; client or human.
`CYODA_JWT_EXPIRY_SECONDS`	int	`3600`	Token lifetime in seconds.
`CYODA_JWT_ISSUER`	string	`cyoda`	JWT issuer claim (iss).
`CYODA_JWT_SIGNING_KEY`	string	—	RSA private key in PEM format; required in jwt mode. Supports _FILE suffix.
`CYODA_OIDC_ALLOW_PRIVATE_NETWORKS`	bool	`false`	Bypass the SSRF blocklist so private-network OIDC providers can be registered; test/dev only, never in production.
`CYODA_OIDC_CONNECTION_REQUEST_TIMEOUT_MS`	int	`5000`	Connection-pool request timeout in milliseconds for OIDC discovery and JWKS endpoint fetches.
`CYODA_OIDC_CONNECT_TIMEOUT_MS`	int	`5000`	TCP connect timeout in milliseconds for OIDC discovery and JWKS endpoint fetches.
`CYODA_OIDC_REQUIRE_HTTPS`	bool	`true`	Reject federated OIDC provider registration when the well-known config URI is not https.
`CYODA_OIDC_ROLES_CLAIM`	string	`roles`	JWT claim name from which role values are read for tokens issued by a federated OIDC provider.
`CYODA_OIDC_SOCKET_TIMEOUT_MS`	int	`5000`	HTTP read timeout in milliseconds for OIDC discovery and JWKS endpoint fetches.
`CYODA_REQUIRE_JWT`	bool	`false`	Production safety floor; refuses to start unless IAM mode is jwt and a signing key is set.

cluster (12)

Variable	Type	Default	Description
`CYODA_CLUSTER_ENABLED`	bool	`false`	Enable multi-node clustering.
`CYODA_DISPATCH_FORWARD_TIMEOUT`	duration	`30s`	HTTP timeout for the cross-node forwarding call.
`CYODA_DISPATCH_WAIT_TIMEOUT`	duration	`5s`	How long the dispatcher polls gossip for a compute member with matching tags.
`CYODA_GOSSIP_ADDR`	string	`:7946`	Gossip protocol listen address ([host]:port).
`CYODA_GOSSIP_STABILITY_WINDOW`	duration	`2s`	Gossip stability window.
`CYODA_GRPC_NODE_ADDR`	string	—	This node's gRPC endpoint advertised to peers (host:port, no scheme).
`CYODA_HMAC_SECRET`	string	—	Hex-encoded HMAC secret for inter-node dispatch authentication; required when CYODA_CLUSTER_ENABLED=true. Supports _FILE suffix.
`CYODA_NODE_ADDR`	string	`http://localhost:8080`	This node's HTTP base URL; must include scheme.
`CYODA_NODE_ID`	string	—	Unique node identifier; required when CYODA_CLUSTER_ENABLED=true.
`CYODA_PROXY_TIMEOUT`	duration	`30s`	Request proxy timeout.
`CYODA_SEED_NODES`	csv	—	Comma-separated list of seed node addresses.
`CYODA_TX_TOKEN_TTL`	duration	`1m30s`	TTL of the signed transaction routing token minted on processor/criteria dispatch.

cors (2)

Variable	Type	Default	Description
`CYODA_CORS_ALLOWED_ORIGINS`	csv	—	Comma-separated allowed origins, or * for wildcard mode; empty selects loopback mode.
`CYODA_CORS_ENABLED`	bool	`true`	Enable CORS middleware; false hands CORS handling to an upstream ingress.

database (15)

Variable	Type	Default	Description
`CYODA_POSTGRES_ACQUIRE_TIMEOUT`	—	`10s`	Maximum wait for a free pooled connection before failing with 503; 0 disables
`CYODA_POSTGRES_AUTO_MIGRATE`	—	`true`	Run embedded SQL migrations on startup
`CYODA_POSTGRES_IDLE_IN_TX_TIMEOUT`	—	`5m`	Maximum time a connection may sit idle inside an open transaction; 0 disables
`CYODA_POSTGRES_MAX_CONNS`	—	`25`	Max pool connections
`CYODA_POSTGRES_MAX_CONN_IDLE_TIME`	—	`5m`	Max idle time before closing connection
`CYODA_POSTGRES_MIGRATE_LOCK_TIMEOUT`	—	`5m`	Maximum lock wait during schema migration; 0 disables
`CYODA_POSTGRES_MIN_CONNS`	—	`5`	Min pool connections
`CYODA_POSTGRES_SEARCH_STATEMENT_TIMEOUT`	—	`30m`	Statement ceiling for async search scans; 0 disables
`CYODA_POSTGRES_STATEMENT_TIMEOUT`	—	`5m`	Maximum run time for a single SQL statement; 0 disables
`CYODA_POSTGRES_URL`	—	—	PostgreSQL connection string
`CYODA_SQLITE_AUTO_MIGRATE`	—	`true`	Run embedded SQL migrations on startup
`CYODA_SQLITE_BUSY_TIMEOUT`	—	`5s`	Wait time for write lock
`CYODA_SQLITE_CACHE_SIZE`	—	`64000`	Page cache in KiB, per connection
`CYODA_SQLITE_PATH`	—	`$XDG_DATA_HOME/cyoda/cyoda.db (Windows: %LocalAppData%\cyoda\cyoda.db)`	Database file path
`CYODA_SQLITE_READER_POOL_SIZE`	—	`GOMAXPROCS clamped to 4..8`	Max concurrent reader connections; each holds its own page cache

grpc (6)

Variable	Type	Default	Description
`CYODA_COMPUTE_GRPC_ENDPOINT`	string	—	gRPC endpoint for a compute node to connect to (compute-client side).
`CYODA_COMPUTE_HTTP_BASE`	string	—	HTTP base URL of the cyoda instance a compute node calls back into (compute-client side).
`CYODA_COMPUTE_TOKEN`	string	—	Bearer token for compute-node authentication (compute-client side).
`CYODA_GRPC_PORT`	int	`9090`	gRPC listen port.
`CYODA_KEEPALIVE_INTERVAL`	int	`10`	Seconds between server keep-alive pings to each compute member; also the transport keepalive idle time.
`CYODA_KEEPALIVE_TIMEOUT`	int	`30`	Seconds of inbound silence or write stall before a compute member is evicted; also the transport keepalive ack timeout.

scheduler (7)

Variable	Type	Default	Description
`CYODA_SCHEDULER_BATCH_SIZE`	int	`100`	Max due tasks pulled per scan.
`CYODA_SCHEDULER_COORDINATOR`	string	`lowest-node-id`	Coordinator-election strategy.
`CYODA_SCHEDULER_DISTRIBUTION`	string	`round-robin`	Dispatch-target selection strategy: round-robin or self. Forced to self when CYODA_CLUSTER_ENABLED=false.
`CYODA_SCHEDULER_ENABLED`	bool	`true`	Kill switch for the scheduled-transition coordinator scan loop.
`CYODA_SCHEDULER_EXPIRY_GRACE`	duration	`100ms`	Grace band above a scheduled transition's timeoutMs before it is expired instead of fired late; size to at least the max inter-node clock skew.
`CYODA_SCHEDULER_REDISPATCH_BACKOFF`	duration	`30s`	Best-effort re-dispatch throttle window after a due task is picked up.
`CYODA_SCHEDULER_SCAN_INTERVAL`	duration	`1s`	Coordinator scan cadence.

schema (2)

Variable	Type	Default	Description
`CYODA_SCHEMA_EXTEND_MAX_RETRIES`	—	`8`	Max retries on concurrent schema extension
`CYODA_SCHEMA_SAVEPOINT_INTERVAL`	—	`64`	Rows per savepoint during schema extension

search (10)

Variable	Type	Default	Description
`CYODA_SEARCH_ASYNC_MAX_PER_TENANT`	int	`8`	Maximum async-search jobs one tenant may have in flight (queued or running) on a node; further submissions get SEARCH_QUEUE_FULL (retryable 503), so one tenant cannot fill the shared queue. Defaults to CYODA_SEARCH_ASYNC_WORKERS, so it tracks a resized pool. 0 disables the cap. Must be >= 0; startup fails otherwise.
`CYODA_SEARCH_ASYNC_QUEUE`	int	`256`	Async-search submit queue capacity beyond the running workers; Submit returns SEARCH_QUEUE_FULL (retryable 503) once exhausted. Must be >= 0; startup fails otherwise.
`CYODA_SEARCH_ASYNC_WORKERS`	int	`8`	Async-search worker pool size. Must be >= 1; startup fails otherwise.
`CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL`	duration	`15s`	How often a running async-search executor stamps job liveness and polls for cross-node cancel/terminal status, starting at submit time (while queued, not only while scanning). Must be > 0; startup fails otherwise.
`CYODA_SEARCH_JOB_MAX_ATTEMPTS`	int	`3`	Executions an async-search job may consume before it is failed: the initial run plus one per executor lost without a graceful release. Graceful handoffs do not count. Must be >= 1 (1 disables re-execution).
`CYODA_SEARCH_JOB_STALE_AFTER`	duration	`5m`	How long a RUNNING async-search job may go without a heartbeat before the reaper claims it and marks it FAILED. Must be >= 4x CYODA_SEARCH_JOB_HEARTBEAT_INTERVAL; startup fails otherwise.
`CYODA_SEARCH_MAX_SORT_KEYS`	int	`16`	Maximum number of sort keys per search request; values <= 0 clamp to the default.
`CYODA_SEARCH_REAP_INTERVAL`	duration	`5m`	Search snapshot reap interval.
`CYODA_SEARCH_SNAPSHOT_TTL`	duration	`1h`	Search snapshot TTL.
`CYODA_STATS_GROUP_MAX`	int	`10000`	Cardinality ceiling for grouped-stats results; also caps the request limit parameter. Values <= 0 clamp to the default.

server (15)

Variable	Type	Default	Description
`CYODA_CONTEXT_PATH`	string	`/api`	URL prefix for all routes.
`CYODA_DEBUG`	—	—	Reserved; not currently read by the server.
`CYODA_ERROR_RESPONSE_MODE`	string	`sanitized`	Error detail level: sanitized (generic message + ticket UUID for 5xx) or verbose (internal detail included; development only).
`CYODA_HTTP_IDLE_TIMEOUT`	duration	`2m`	How long an idle keep-alive connection is held open between requests. 0 falls back to CYODA_HTTP_READ_TIMEOUT.
`CYODA_HTTP_PORT`	int	`8080`	HTTP listen port.
`CYODA_HTTP_READ_HEADER_TIMEOUT`	duration	`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	`5m`	Time allowed to receive a whole request, body included. Does not limit handler execution. 0 disables.
`CYODA_HTTP_WRITE_TIMEOUT`	duration	`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_LOG_LEVEL`	string	`info`	Log level: debug\|info\|warn\|error.
`CYODA_MAX_STATE_VISITS`	int	`10`	Max visits per state in workflow cascade.
`CYODA_MODEL_CACHE_LEASE`	duration	`5m`	Model cache lease duration; actual expiry is jittered ±10%.
`CYODA_PROFILES`	csv	—	Comma-separated profile names; loads cyoda.<name>.env files before the process's own environment is consulted.
`CYODA_STARTUP_TIMEOUT`	duration	`30s`	Deadline for plugin init, TM init, and (cluster mode) the gossip seed-join retry loop.
`CYODA_STORAGE_BACKEND`	string	`memory`	Storage backend selection (memory\|sqlite\|postgres).
`CYODA_SUPPRESS_BANNER`	bool	`false`	Silence startup and mock-auth banners (CI/tests only).

cyoda help config — cyoda configuration reference
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.
cyoda help config auth — auth configuration
config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.
cyoda help config cluster — cyoda cluster & dispatch configuration
- `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 — CORS configuration
config.cors — Cross-Origin Resource Sharing (CORS) controls for the public HTTP surface.
cyoda help config database — database configuration
config.database — storage backend selection and per-backend connection settings.
cyoda help config grpc — grpc configuration
config.grpc — gRPC listener settings and compute-node credentials.
cyoda help config scheduler — cyoda scheduled-transition scheduler configuration
- `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 — schema configuration
config.schema — schema-extension log tuning.