Skip to content

Configuration reference

Configuration is explicit at several boundaries. Set a value at its owning boundary rather than adding a second environment switch that bypasses the factory.

Owner Purpose Exact declarations
configuration/settings.py Generated project’s validated deployment inputs Project anatomy
CayuConfig Immutable process-wide runtime defaults Configuration API
RunRequest One run’s input and allowed overrides Applications API
AgentSpec Model, prompt and agent capabilities Agents API
ServerConfig Authentication, exposure, CORS and lifecycle Server API
[tool.cayu] Project factory and CLI convention Project convention

The linked API entries contain fields, types, defaults and validators from the documented release. Source expressions such as Field(...) preserve validation bounds and factories rather than replacing them with guessed values.

Project tables

Section titled “Project tables”
[tool.cayu]
factory = "app:build_app"


[tool.cayu.session_store]
backend = "sqlite"
path = "data/cayu.db"


[tool.cayu.serve]
auth = "cayu.server.environment_auth:OPERATOR_BASIC_AUTH"


[tool.cayu.workers]
dispatch = "workers:run_dispatch"

Use the generated project’s existing tables when adding a capability. The factory is a synchronous zero-argument callable. Named workers are async (app, stop) entrypoints. [tool.cayu.scaffold] records the generator’s preset, adapters, capabilities and convention version; it is not runtime authorization.

Environment inputs

Section titled “Environment inputs”
Variable Owner Behavior
CAYU_DATABASE_URL Application stores and storage-aware CLI PostgreSQL or absolute SQLite URL; blank configured values fail
CAYU_DATABASE_POOL_MAX Store pools Positive pool ceiling, default 5 per pool
CAYU_DATABASE_DIRECT_URL PostgreSQL listener and resolved migration/status Direct connection when pooled traffic uses a transaction proxy
CAYU_REQUIRE_POSTGRES SQLite store construction 1 rejects SQLite; 0 or unset does not
CAYU_OPERATOR_USERNAME Environment Basic-auth target Nonblank deployed operator username
CAYU_OPERATOR_PASSWORD Environment Basic-auth target Nonblank deployed secret password
CAYU_WORKER_INDEX Multi-process worker supervisor Zero-based child process index
CAYU_WORKER_COUNT Multi-process worker supervisor Total child count

Provider credentials and model selections belong to the chosen project’s validated settings and provider adapter. Read its generated README and providers guide; there is no universal API key for all providers.

Storage target precedence is explicit CLI selector, environment, project table, then the existing conventional local file. Typed server configuration does not read a secret manager on your behalf. Resolve inputs before constructing it.

Inspect effective settings

Section titled “Inspect effective settings”
Terminal window
cayu inspect --json
cayu check --fail-on warning --json

Inspect reports non-secret configuration and ownership. Check verifies configured readiness without establishing live-provider quality. Preserve failure exit codes in automation. For complete option lookup, use CLI reference.