Configuration

Mandatory (the core refuses to boot otherwise)

The environment variable named by database.kumoss_database_url_env must be set; the variable named by services.iac.token_env must be set (the IaC sidecar is always called and has no enabled flag); the credentials that LiteLLM requires for llm.model and llm.small_model must be set for providers LiteLLM can validate.

Conditionally mandatory

oidc.client_id when oidc.issuer_url is set; the token_env variable of every other enabled sidecar; the variable named by storage.account_key_env when storage.provider is STORAGE_ACCOUNT; a derivable account name in storage.endpoint_url for STORAGE_ACCOUNT; a remote backend declared by every target repository while storage.terraform_state_bucket is blank — which only happens if a deployment explicitly sets it to "", since the shipped value enables Kumoss-managed state by default; web_search.endpoint when web_search.provider is searxng.

Optional with defaults

Everything else.

environment

one of development, staging, production

development

Optional

A label for the deployment tier. Any other value fails validation.

oidc.issuer_url

string

""

Optional

OIDC issuer URL. Blank disables authentication entirely: every request, from anyone who can reach the API, resolves to a fixed local development identity (dev@kumoss.local) that holds the top role of both role groups (devops and panel admin). When set, the core validates bearer JWTs against the issuer’s JWKS, discovered lazily on the first request.

oidc.client_id

string

""

Required when issuer_url is set

Public client id of the SPA. Validation error otherwise: oidc.issuer_url is set but oidc.client_id is empty; set oidc.client_id (and optionally oidc.audience) in config.yaml.

oidc.audience

string

""

Optional

Expected aud claim. Blank accepts client_id and api://<client_id>. Needed for identity providers that issue tokens for a separately named API (Auth0, Okta).

oidc.scope

string

"openid profile email"

Optional

Scopes the SPA requests. A {client_id} placeholder is expanded at load time (and fails validation if client_id is blank). When left at the default and the issuer host is login.microsoftonline.com, api://{client_id}/.default is appended automatically.

oidc.clock_skew_seconds

integer

60

Optional

Leeway applied to exp, iat, and nbf validation.

admin.default_root_email

string

""

Optional

Bootstrap administrator. A user whose access token carries an email claim equal to this address (case-insensitive) and email_verified: true is elevated to devops plus panel admin on login, and re-checked on every request. Elevation is one-way: clearing the field never demotes anyone. Identity providers that never emit email_verified (Entra ID, Auth0, Okta) cannot use this; grant the first admin in the database instead, as described in Bootstrap admin. Ignored while authentication is disabled.

services.<name>.enabled (not for iac)

boolean

false

false for notifications, mapping, authz

Optional

Whether the core calls the sidecar. A disabled sidecar is never contacted: mapping is done locally, notifications are dropped, and authorization answers "authorized". Compose still starts the bundled notifications container; mapping and authorization have no bundled container. An enabled key under services.iac is ignored.

services.<name>.endpoint

string (base URL)

"" for notifications, mapping, authz; http://iac:8082 for iac (its own code default, not just the shipped value)

http://notifications:8080, http://iac:8082; "" for mapping and authz (no bundled implementation)

Conditional (needed when enabled; always for iac)

Base URL the core calls, resolvable from inside the core container. An empty services.iac.endpoint aborts the boot with services.iac.endpoint is empty; the IaC service is mandatory. Point it at an implementation of the iac contract. An enabled optional sidecar with an empty endpoint also aborts the boot, with Enabled services have no endpoint: services.<name>.endpoint. Point each at an implementation of its contract, or flip it to enabled: false.

services.<name>.token_env

string (variable name)

"" for notifications, mapping, authz; KUMOSS_IAC_TOKEN for iac (its own code default)

KUMOSS_NOTIFICATIONS_TOKEN, KUMOSS_MAPPING_TOKEN, KUMOSS_AUTHZ_TOKEN, KUMOSS_IAC_TOKEN

Conditional (always for iac)

Name of the environment variable holding the bearer token sent on every call. A sidecar the core will call whose variable resolves to an empty value aborts the boot with Services the core calls have no bearer token in the environment: services.<name> → $<VAR>. Set the listed env vars; the optional sidecars can also be flipped to enabled: false (services.iac cannot — it is mandatory).

services.<name>.timeout

float (seconds)

30.0

30.0

Optional

Per-request HTTP budget. Every sidecar call returns promptly (long work runs as jobs the core polls), so this covers one round trip only. Honoured by the IaC and notifications clients; the mapping and authorization clients currently use fixed budgets of 10 and 15 seconds and ignore this field.

services.iac.job_poll_interval

float (seconds)

5.0

Optional

How often the core polls GET /v1/jobs/{job_id} for a submitted engine command.

services.iac.job_timeout

float (seconds)

3600.0

Optional

Maximum total wait for one job. It must cover both the time the job spends queued (jobs on the same workspace run one at a time, in order) and the command itself. The bundled sidecar imposes no timeout of its own on the engine process, so this value is the only bound. A validation run submits several jobs in sequence (init, validate, plan, and show when drift is requested), each with its own job_timeout.

orchestration.enable_compliance_checker

boolean

false

true

Optional

Runs the compliance auditor once a generate round has been validated and its report written: a second, independent small-model agent reads the session’s first request and the raw plan, and checks them against the rules in the general-compliance-report prompt. The session is locked if any finding comes back with severity error or critical; warning findings are recorded in the report but do not lock. The report is stored as a round artifact and shown in the portal. A lock also sends an iac.compliance.failed notification. When false the audit is skipped entirely and reported as an empty passing result, so it can never lock and nothing is stored. Generate rounds only — drift rounds do not audit, and apply does not re-audit.

orchestration.block_on_high_impact

boolean

false

true

Optional

Locks the session when the generate report’s impact banner comes back high, and sends an iac.impact.high notification. The banner itself — low, medium, or high, judged against the general-compliance-impact prompt criteria — is part of every report either way; this flag decides only whether it gates. It is evaluated independently of the auditor above: the round ends locked if either condition fires.

orchestration.max_drift_reports

integer

3

3

Optional

Maximum detect-and-remediate iterations in a drift session.

orchestration.max_validation_iteration

integer

8

5

Optional

Maximum generate-then-validate attempts per generation task before the round fails with Validation loop exceeded.

orchestration.max_import_iteration

integer

5

5

Optional

Maximum generate-then-import attempts in an import round. A failed plan or a rejected import is fed back to the generator and counts as one attempt. When the attempts run out after a passing plan, the round still reports what did import and lists what did not.

orchestration.max_tool_agent_executions

integer

40

40

Optional

Maximum model turns inside one agent loop. On the last turn only the agent’s sentinel tool is offered, so the agent can still return what it has; a loop that reaches the limit anyway aborts with ToolExecutionsExceeded and the round fails. Renamed from max_tool_chain_executions: the old key is ignored, so a file that still sets it silently gets the built-in 40. See Agent tool loop.

orchestration.max_session_events_iteration

integer

2160

2160

Optional

Number of polls a server-sent-events subscription performs before it closes. The loop sleeps 4 or 5 seconds depending on the branch taken, so 2160 iterations run for roughly three hours rather than exactly 2160 × 5s.

orchestration.drift_group_operations

integer

8

8

Optional

How many drift operations are grouped into one remediation task.

orchestration.pull_request_readiness_seconds

integer

10

10

Optional

How many one-second polls the GitHub provider performs waiting for a pull request to become mergeable before failing with readiness polling exhausted.

llm.model

string (LiteLLM model string, or a model_name alias when model_list is set)

anthropic/claude-sonnet-5

main (an llm.model_list alias)

Optional (credentials mandatory)

High-quality model used by the IaC generator, target generator, and report generator chains.

llm.small_model

string

anthropic/claude-haiku-4-5

small (an llm.model_list alias)

Optional (credentials mandatory)

Cheaper model used by every other chain and by tool-internal LLM calls, including the web_search summarisation.

llm.temperature

float

0.1

0.1

Optional

Applied to both roles (forced to 1.0 when a chain requests extended thinking).

llm.max_output_tokens

integer

32000

32000

Optional

Completion cap sent on every call.

llm.timeout

float (seconds, must be > 0)

600.0

600

Optional

Per-request budget LiteLLM enforces on a single inference call, chat completions and the web-search Responses path alike. Each of the three internal retries gets a fresh budget.

llm.model_list

list of LiteLLM Router entries

[]

2 entries

Optional

Advanced routing: load balancing across entries that share a model_name, per-entry endpoints, and os.environ/VAR credential references. Router-level fallbacks between different models are not configurable today; the core passes only model_list to the Router. When non-empty, model and small_model must match a model_name and boot validation runs against the listed entries. As shipped, the aliases are main (a self-hosted OpenAI-compatible endpoint with a per-entry api_base and os.environ/-referenced key) and small (vertex_ai/claude-sonnet-5-5).

web_search.provider

string — a LiteLLM search provider name

searxng

searxng

Optional

Selects the search engine called by the web_search tool. The shipped stack deploys a SearXNG sidecar and leaves this at searxng. Any name in litellm.types.utils.SearchProviders is accepted — tavily, brave, perplexity, exa_ai, google_pse and others — but a hosted provider reads credentials from its own env vars, ignores endpoint, and needs a search service the stack does not ship: you have to provide that backend yourself. Empty disables web search altogether: there is no LLM-native fallback, so the tool answers "unavailable" instead of asking the model to search for itself. That is what lets self-hosted OpenAI-compatible endpoints (vLLM and the like) get live results.

web_search.endpoint

string (URL)

http://localhost:8888

http://searxng:8888

Conditional

Base URL of the search service, passed to LiteLLM as api_base. Required for searxng; hosted providers take their credentials from environment variables instead and usually need no endpoint.

web_search.max_results

integer (1–20)

5

8

Optional

Upper bound on results returned per query.

web_search.max_page_chars

integer (500–20000)

6000

10000

Optional

Truncates the readable text extracted from each result page. That product — max_results × max_page_chars — is the summarising inferences' input; the agent sees only the summaries.

web_search.timeout

float (seconds, must be > 0)

30.0

30.0

Optional

Per-request HTTP budget, covering the engine call and each page read.

web_search.summarize_top

integer (1–10)

1

commented out

Optional

How many of the ranked summaries reach the agent, most relevant first.

web_search.summarize_max_chars

integer (500–20000)

4000

commented out

Optional

Caps each summary, and each raw excerpt kept when a page’s summary inference fails. A summary stands in for its page, so too low a value loses detail the agent cannot get back.

paths.upload_folder

path

/workspaces

Optional

Directory where the core clones repositories, one session directory each. Must be writable by the core and shared with the IaC sidecar at the same path: in the compose stack both containers mount the workspaces volume at /workspaces, and both images run as the same unprivileged user (kumoss, uid and gid 10001).

paths.session_plan_filename

string matching ^[A-Za-z0-9._-]{1,128}$

session.plan

Optional

Name of the plan artifact written by plan into the session workspace, carried by the pinned workspace, and executed by apply. It must be a single safe filename: no path separators, no spaces, at most 128 characters. Keep the .plan suffix so the gitignore rules the core injects continue to cover it.

paths.backend_override_filename

string matching ^[A-Za-z0-9._-]{1,128}_override\.tf$

backend_override.tf

Optional

Name of the state backend override the core writes into every workspace before init when storage.terraform_state_bucket is set. It must be a single safe filename ending in _override.tf: Terraform only merges files with that suffix over the rest of the configuration, and the gitignore rules the core injects only cover that suffix. The file holds the state store credentials, so the agent’s file tools can neither see nor touch it.

database.kumoss_database_url_env

string (variable name)

KUMOSS_SQL_DATABASE_URL

Optional (the variable it names is mandatory)

Name of the environment variable that holds the actual PostgreSQL connection URL. URLs embed credentials, which is why the URL itself is not in this file. Boot fails with Missing env variable for kumoss database when the variable is empty, and database initialisation fails when it is unreachable. A postgresql:// scheme is rewritten to postgresql+asyncpg://, and a sslmode= query parameter to asyncpg’s ssl=, so URLs copied from a managed PostgreSQL service work as-is.

redis.redis_url_env

string (variable name)

KUMOSS_REDIS_URL

Optional

Name of the variable holding the Redis URL (which may embed a password).

redis.default_url

string

redis://redis:6379/0

Optional

Fallback used when the variable is unset or empty. The default points at the compose service, so the stack needs no Redis variable.

redis.max_connections

integer

20

Optional

Connection pool size.

redis.socket_connect_timeout

float (seconds)

2.0

Optional

Connect timeout.

redis.socket_timeout

float (seconds)

2.0

Optional

Read and write timeout.

redis.pool_timeout

float (seconds)

2.0

Optional

How long a request may wait for a free pooled connection.

telemetry.collector_url

string (base URL ending in /)

http://phoenix:6006/

http://phoenix:6006/

Optional

Base URL of the trace collector. The core appends v1/traces by plain string concatenation, so the value must end with a slash: http://phoenix:6006/ becomes http://phoenix:6006/v1/traces. The same URL is used as the Phoenix client base URL for prompt seeding and fetching, so today it must point at a Phoenix server even if you export traces elsewhere. The default is the Phoenix service of the bundled stack; running the core outside docker needs an explicit http://localhost:6006/.

telemetry.otel_attribute_count_limit

integer

1024

1024

Optional

Maximum number of attributes per span (attribute count, not length). When exceeded the SDK drops the oldest attributes first, which on LLM spans are the session and user identifiers and the span kind.

telemetry.otel_console_exporter

boolean

false

false

Optional

Also print every span to the core’s standard output. Spans contain prompts and plans; do not enable this where logs are shared.

http.cors_origins

list of strings

["http://localhost"]

Optional

Browser origins allowed by CORS. The compose stack serves the SPA from nginx on port 80, so http://localhost is enough. Add http://localhost:5173 when running the Vite dev server against the API container. Set your real origin for a deployed instance.

storage.provider

one of RUSTFS, S3, STORAGE_ACCOUNT (enum names) or rustfs, s3, storage_account (enum values)

RUSTFS

Optional

Backend. RUSTFS: the bundled RustFS or any S3-compatible server with a custom endpoint. S3: real AWS S3 on its regional endpoint (both URLs below are ignored; the region builds the endpoint). STORAGE_ACCOUNT: an Azure storage account using a shared key.

storage.bucket

string

kumoss-artifacts

Optional

Artifacts bucket name, or blob container name for STORAGE_ACCOUNT. Created at boot if missing.

storage.terraform_state_bucket

string

kumoss-terraform-state, both as shipped in config.yaml and as the field default if the key is absent

Optional

Bucket (or blob container) holding Terraform/OpenTofu state, separate from storage.bucket. Non-blank — the shipped value — means Kumoss manages state: the bucket is created at boot if missing and the core writes paths.backend_override_filename into every workspace before init, addressing it with the key <project_id>/<storage.terraform_state_filename>. Backend type follows storage.provider (s3 for RUSTFS/S3, azurerm for STORAGE_ACCOUNT). Set it explicitly to "" to opt out — no value, "", and whitespace-only are all blank, and blank means no bucket is created, no override is written, and each repository must declare its own remote backend, whose credentials belong to the IaC sidecar. A bare terraform_state_bucket: with nothing after it is not the same as "": it parses as YAML null and fails boot with a Pydantic validation error. See Configure state backends.

storage.terraform_state_filename

string matching ^[A-Za-z0-9._-]{1,128}$

terraform.tfstate

Optional

Object name of each project’s state inside storage.terraform_state_bucket, stored under the <project_id>/ prefix. It must be a single safe filename: no path separators, no spaces, at most 128 characters. Changing it orphans the existing state: every project then starts from an empty state under the new key.

storage.endpoint_url

string

http://object-storage:9000

Conditional

Endpoint the core’s SDK calls from inside the compose network. For STORAGE_ACCOUNT it must be the account blob endpoint (https://<account>.blob.core.windows.net, or the emulator form http://<host>:<port>/<account>); the account name is derived from it. Boot fails with storage.endpoint_url must be an account blob endpoint …​ when it cannot be derived.

storage.public_endpoint_url

string

http://localhost:9000

Conditional

Host the browser reaches. Presigned S3 URLs bind the host header, so this must be the externally visible address of the store (in the compose stack, nginx forwards port 9000 to RustFS).

storage.region

string

us-east-1

Optional

Region for signing (RUSTFS) or for building the endpoint (S3). Ignored for STORAGE_ACCOUNT.

storage.access_key_env

string (variable name)

RUSTFS_ACCESS_KEY

Optional

Variable holding the access key. Falls back to rustfsadmin for RUSTFS when unset; empty for S3, which then uses the AWS SDK default credential chain. A non-empty value always wins, so blank RUSTFS_ACCESS_KEY and RUSTFS_SECRET_KEY in core/.env when switching to S3 (the sample ships them set to rustfsadmin).

storage.secret_key_env

string (variable name)

RUSTFS_SECRET_KEY

Optional

Variable holding the secret key, same fallback rules.

storage.account_key_env

string (variable name)

STORAGE_ACCOUNT_KEY

Optional (the variable is mandatory for STORAGE_ACCOUNT)

Variable holding the Azure shared key. Boot fails with storage.provider STORAGE_ACCOUNT requires env var STORAGE_ACCOUNT_KEY. when empty.

storage.connect_timeout

float (seconds)

3.0

Optional

Per-request connect budget.

storage.read_timeout

float (seconds)

10.0

Optional

Per-request read budget.

storage.max_attempts

integer

3

Optional

Retry count (botocore standard mode).

storage.presign_expiry_seconds

integer in [108000, 604800]

172800 (48 hours)

Optional

Lifetime of presigned download URLs. Must stay between 108000 (30 hours) and 604800 (7 days). The floor keeps URLs valid for longer than the 24-hour cached session detail that embeds them; the ceiling is the SigV4 limit. Boot fails with storage.presign_expiry_seconds must be between 108000 …​ and 604800 …​ otherwise.

git.provider

one of GITHUB, AZURE_DEVOPS, GITLAB (enum names) or github.com, dev.azure.com, gitlab.com (enum values)

GITHUB

Optional

Git hosting provider. Selects the pull-request API implementation and the host written into ~/.git-credentials. Any other value, including an empty string, fails validation. The pull-request adapters support only the public SaaS hosts: github.com, gitlab.com (top-level namespace and project, no subgroups), and dev.azure.com. GitHub Enterprise Server, self-managed GitLab, and *.visualstudio.com URLs are rejected as malformed at pull-request time.

git.pat_user_env

string (variable name)

GIT_USER

Optional

Variable holding the account username.

git.pat_token_env

string (variable name)

GIT_TOKEN

Optional

Variable holding the personal access token.

git.author_name

string

Kumoss

Optional

Commit author name.

git.author_email

string

kumoss@noreply.invalid

Optional

Commit author e-mail.