Configuration

Canonical reference: cyoda help config

This page is the narrative; the binary is authoritative.

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:

1. Shell environment
2. .env.{profile} files (in CYODA_PROFILES declaration order; later profiles override earlier ones within their group)
3. .env in the project directory
4. User config file
5. System config file
6. 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 (25)

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_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.

database (10)

Variable	Type	Default	Description
CYODA_POSTGRES_AUTO_MIGRATE	—	true	Run embedded SQL migrations on startup
CYODA_POSTGRES_MAX_CONNS	—	25	Max pool connections
CYODA_POSTGRES_MAX_CONN_IDLE_TIME	—	5m	Max idle time before closing connection
CYODA_POSTGRES_MIN_CONNS	—	5	Min pool connections
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
CYODA_SQLITE_PATH	—	$XDG_DATA_HOME/cyoda/cyoda.db (Windows: %LocalAppData%\cyoda\cyoda.db)	Database file path
CYODA_SQLITE_SEARCH_SCAN_LIMIT	—	100000	Max rows examined per search with residual filter

grpc (4)

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.

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 (4)

Variable	Type	Default	Description
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 (11)

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_PORT	int	8080	HTTP listen port.
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).

tx (3)

Variable	Type	Default	Description
CYODA_TX_OUTCOME_TTL	duration	5m	Transaction outcome TTL.
CYODA_TX_REAP_INTERVAL	duration	10s	Transaction reap interval.
CYODA_TX_TTL	duration	1m	Transaction TTL.

Related topics

• 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 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 schema — schema configuration
  config.schema — schema-extension log tuning.