{
  "topic": "config",
  "path": [
    "config"
  ],
  "title": "cyoda configuration reference",
  "synopsis": "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.",
  "body": "# config\n\n## NAME\n\nconfig — environment-driven configuration for cyoda.\n\n## SYNOPSIS\n\nAll configuration is environment variables prefixed with `CYODA_`. Topics group related variables:\n\n- `config.database` — storage backend selection, per-backend connection settings\n- `config.auth` — IAM mode, JWT issuer, admin controls\n- `config.grpc` — gRPC listener and compute-node credentials\n- `config.schema` — schema-extension log tuning\n\n## DESCRIPTION\n\n### Precedence\n\nEnvironment 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.\n\n### _FILE suffix support\n\nThe 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.\n\n- `CYODA_JWT_SIGNING_KEY` / `CYODA_JWT_SIGNING_KEY_FILE`\n- `CYODA_HMAC_SECRET` / `CYODA_HMAC_SECRET_FILE`\n- `CYODA_BOOTSTRAP_CLIENT_SECRET` / `CYODA_BOOTSTRAP_CLIENT_SECRET_FILE`\n- `CYODA_METRICS_BEARER` / `CYODA_METRICS_BEARER_FILE`\n\n### Profile loader\n\n`CYODA_PROFILES` is a comma-separated list of profile names. For each name `N`, a file\n`cyoda.N.env` is loaded from the working directory before the process's own environment is\nconsulted. This supports local development without exporting many variables.\n\n**Example:**\n\n```\nCYODA_PROFILES=postgres,otel go run ./cmd/cyoda\n```\n\nloads `cyoda.postgres.env` and `cyoda.otel.env` from the working directory.\n\n### Server options\n\n- `CYODA_HTTP_PORT` (int, default: `8080`) — HTTP listen port.\n- `CYODA_CONTEXT_PATH` (string, default: `/api`) — URL prefix for all routes.\n- `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).\n- `CYODA_LOG_LEVEL` (string, default: `info`) — accepted: `debug|info|warn|error`.\n- `CYODA_SUPPRESS_BANNER` (bool, default: `false`) — silence startup and mock-auth banners.\n- `CYODA_STARTUP_TIMEOUT` (duration, default: `30s`) — deadline for plugin init, TM init, and (cluster mode) the gossip seed-join retry loop.\n- `CYODA_DEBUG` — reserved; not currently read by the server.\n- `CYODA_MAX_STATE_VISITS` (int, default: `10`) — max visits per state in workflow cascade.\n- `CYODA_MODEL_CACHE_LEASE` (duration, default: `5m`) — model cache lease duration; actual expiry is jittered ±10%.\n\n### Admin and metrics\n\n- `CYODA_ADMIN_PORT` (int, default: `9091`) — admin port for health and metrics.\n- `CYODA_ADMIN_BIND_ADDRESS` (string, default: `127.0.0.1`) — admin listener bind address.\n- `CYODA_METRICS_REQUIRE_AUTH` (bool, default: `false`) — require Bearer auth on `/metrics`; startup fails if `true` and `CYODA_METRICS_BEARER` is empty.\n- `CYODA_METRICS_BEARER` (string, default: unset) — static Bearer token for `GET /metrics`. Supports `_FILE` suffix.\n- `CYODA_OTEL_ENABLED` (bool, default: `false`) — enable OpenTelemetry tracing and metrics.\n\n### Search and transaction internals\n\n- `CYODA_SEARCH_SNAPSHOT_TTL` (duration, default: `1h`) — search snapshot TTL.\n- `CYODA_SEARCH_REAP_INTERVAL` (duration, default: `5m`) — search snapshot reap interval.\n- `CYODA_TX_TTL` (duration, default: `60s`) — transaction TTL.\n- `CYODA_TX_REAP_INTERVAL` (duration, default: `10s`) — transaction reap interval.\n- `CYODA_TX_OUTCOME_TTL` (duration, default: `5m`) — transaction outcome TTL.\n\n### Cluster and dispatch\n\n- `CYODA_CLUSTER_ENABLED` (bool, default: `false`) — enable multi-node clustering.\n- `CYODA_NODE_ID` (string, default: unset) — unique node identifier; required when `CYODA_CLUSTER_ENABLED=true`; any non-empty string is accepted.\n- `CYODA_NODE_ADDR` (string, default: `http://localhost:8080`) — this node's HTTP base URL; must include scheme (`http://` or `https://`).\n- `CYODA_GOSSIP_ADDR` (string, default: `:7946`) — gossip protocol listen address; format `[host]:port` — parsed via `net.SplitHostPort`; invalid format causes startup failure.\n- `CYODA_GOSSIP_STABILITY_WINDOW` (duration, default: `2s`) — gossip stability window.\n- `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.\n- `CYODA_HMAC_SECRET` (string, default: unset) — hex-encoded HMAC secret for inter-node dispatch authentication; required when `CYODA_CLUSTER_ENABLED=true`. Supports `_FILE` suffix.\n- `CYODA_PROXY_TIMEOUT` (duration, default: `30s`) — request proxy timeout.\n- `CYODA_DISPATCH_WAIT_TIMEOUT` (duration, default: `5s`) — how long the dispatcher polls gossip for a compute member with matching tags.\n- `CYODA_DISPATCH_FORWARD_TIMEOUT` (duration, default: `30s`) — HTTP timeout for the cross-node forwarding call.\n- `CYODA_KEEPALIVE_INTERVAL` (int, default: `10`) — keep-alive send interval in seconds.\n- `CYODA_KEEPALIVE_TIMEOUT` (int, default: `30`) — keep-alive timeout in seconds.\n\n## SEE ALSO\n\n- cli\n- run\n- config.auth\n- config.database\n- config.grpc\n- config.schema\n",
  "sections": [
    {
      "name": "NAME",
      "body": "config — environment-driven configuration for cyoda."
    },
    {
      "name": "SYNOPSIS",
      "body": "All configuration is environment variables prefixed with `CYODA_`. Topics group related variables:\n\n- `config.database` — storage backend selection, per-backend connection settings\n- `config.auth` — IAM mode, JWT issuer, admin controls\n- `config.grpc` — gRPC listener and compute-node credentials\n- `config.schema` — schema-extension log tuning"
    },
    {
      "name": "DESCRIPTION",
      "body": "### Precedence\n\nEnvironment 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.\n\n### _FILE suffix support\n\nThe 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.\n\n- `CYODA_JWT_SIGNING_KEY` / `CYODA_JWT_SIGNING_KEY_FILE`\n- `CYODA_HMAC_SECRET` / `CYODA_HMAC_SECRET_FILE`\n- `CYODA_BOOTSTRAP_CLIENT_SECRET` / `CYODA_BOOTSTRAP_CLIENT_SECRET_FILE`\n- `CYODA_METRICS_BEARER` / `CYODA_METRICS_BEARER_FILE`\n\n### Profile loader\n\n`CYODA_PROFILES` is a comma-separated list of profile names. For each name `N`, a file\n`cyoda.N.env` is loaded from the working directory before the process's own environment is\nconsulted. This supports local development without exporting many variables.\n\n**Example:**\n\n```\nCYODA_PROFILES=postgres,otel go run ./cmd/cyoda\n```\n\nloads `cyoda.postgres.env` and `cyoda.otel.env` from the working directory.\n\n### Server options\n\n- `CYODA_HTTP_PORT` (int, default: `8080`) — HTTP listen port.\n- `CYODA_CONTEXT_PATH` (string, default: `/api`) — URL prefix for all routes.\n- `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).\n- `CYODA_LOG_LEVEL` (string, default: `info`) — accepted: `debug|info|warn|error`.\n- `CYODA_SUPPRESS_BANNER` (bool, default: `false`) — silence startup and mock-auth banners.\n- `CYODA_STARTUP_TIMEOUT` (duration, default: `30s`) — deadline for plugin init, TM init, and (cluster mode) the gossip seed-join retry loop.\n- `CYODA_DEBUG` — reserved; not currently read by the server.\n- `CYODA_MAX_STATE_VISITS` (int, default: `10`) — max visits per state in workflow cascade.\n- `CYODA_MODEL_CACHE_LEASE` (duration, default: `5m`) — model cache lease duration; actual expiry is jittered ±10%.\n\n### Admin and metrics\n\n- `CYODA_ADMIN_PORT` (int, default: `9091`) — admin port for health and metrics.\n- `CYODA_ADMIN_BIND_ADDRESS` (string, default: `127.0.0.1`) — admin listener bind address.\n- `CYODA_METRICS_REQUIRE_AUTH` (bool, default: `false`) — require Bearer auth on `/metrics`; startup fails if `true` and `CYODA_METRICS_BEARER` is empty.\n- `CYODA_METRICS_BEARER` (string, default: unset) — static Bearer token for `GET /metrics`. Supports `_FILE` suffix.\n- `CYODA_OTEL_ENABLED` (bool, default: `false`) — enable OpenTelemetry tracing and metrics.\n\n### Search and transaction internals\n\n- `CYODA_SEARCH_SNAPSHOT_TTL` (duration, default: `1h`) — search snapshot TTL.\n- `CYODA_SEARCH_REAP_INTERVAL` (duration, default: `5m`) — search snapshot reap interval.\n- `CYODA_TX_TTL` (duration, default: `60s`) — transaction TTL.\n- `CYODA_TX_REAP_INTERVAL` (duration, default: `10s`) — transaction reap interval.\n- `CYODA_TX_OUTCOME_TTL` (duration, default: `5m`) — transaction outcome TTL.\n\n### Cluster and dispatch\n\n- `CYODA_CLUSTER_ENABLED` (bool, default: `false`) — enable multi-node clustering.\n- `CYODA_NODE_ID` (string, default: unset) — unique node identifier; required when `CYODA_CLUSTER_ENABLED=true`; any non-empty string is accepted.\n- `CYODA_NODE_ADDR` (string, default: `http://localhost:8080`) — this node's HTTP base URL; must include scheme (`http://` or `https://`).\n- `CYODA_GOSSIP_ADDR` (string, default: `:7946`) — gossip protocol listen address; format `[host]:port` — parsed via `net.SplitHostPort`; invalid format causes startup failure.\n- `CYODA_GOSSIP_STABILITY_WINDOW` (duration, default: `2s`) — gossip stability window.\n- `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.\n- `CYODA_HMAC_SECRET` (string, default: unset) — hex-encoded HMAC secret for inter-node dispatch authentication; required when `CYODA_CLUSTER_ENABLED=true`. Supports `_FILE` suffix.\n- `CYODA_PROXY_TIMEOUT` (duration, default: `30s`) — request proxy timeout.\n- `CYODA_DISPATCH_WAIT_TIMEOUT` (duration, default: `5s`) — how long the dispatcher polls gossip for a compute member with matching tags.\n- `CYODA_DISPATCH_FORWARD_TIMEOUT` (duration, default: `30s`) — HTTP timeout for the cross-node forwarding call.\n- `CYODA_KEEPALIVE_INTERVAL` (int, default: `10`) — keep-alive send interval in seconds.\n- `CYODA_KEEPALIVE_TIMEOUT` (int, default: `30`) — keep-alive timeout in seconds."
    },
    {
      "name": "SEE ALSO",
      "body": "- cli\n- run\n- config.auth\n- config.database\n- config.grpc\n- config.schema"
    }
  ],
  "see_also": [
    "cli",
    "run",
    "config.auth",
    "config.database",
    "config.grpc",
    "config.schema"
  ],
  "stability": "stable",
  "actions": [],
  "children": [
    "config.auth",
    "config.database",
    "config.grpc",
    "config.schema"
  ]
}