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.
.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.
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.
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.
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 (26)
Variable
Type
Default
Description
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 (14)
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_KEEPALIVE_INTERVAL
int
10
Keep-alive send interval in seconds.
CYODA_KEEPALIVE_TIMEOUT
int
30
Keep-alive timeout in seconds.
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.
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.
- `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_KEEPALIVE_INTERVAL` (int, default: `10`) — keep-alive send interval in seconds.
- `CYODA_KEEPALIVE_TIMEOUT` (int, default: `30`) — keep-alive timeout in seconds.
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.
