Configuration

How configuration works#

kaveo follows the 12-factor model: every setting is an environment variable. The api and the worker read them at startup, and most names carry the prefix KAVEO_. A few are read without it: DATABASE_URL, MIGRATE_DATABASE_URL and MIGRATIONS_DIR, the standard AWS_* SDK variables, and the hosted AI keys, which are also accepted under their usual names (ANTHROPIC_API_KEY, OPENAI_API_KEY, and XAI_API_KEY or GROK_API_KEY).

Detector thresholds and KAVEO_KEV_CATALOG_PATH are read once, when the detector code loads. A non-integer threshold falls back to its default, and an unknown KAVEO_DETECT_MIN_SEVERITY turns the severity floor off, so a typo never stops a scan. Suppression is stamped at scan time: a change applies to new scans, and past scans keep their labels.

The images do not contain a .env file. A value reaches kaveo only when Docker Compose passes it into the container.

How settings reach the containers#

An override file can pull each value from .env, so secrets stay out of the override itself:

# compose.override.yml
x-kaveo-extra: &kaveo-extra
  KAVEO_REMEDIATION_EXECUTOR: ${KAVEO_REMEDIATION_EXECUTOR:-offline}
  KAVEO_SLACK_WEBHOOK_URL: ${KAVEO_SLACK_WEBHOOK_URL:-}

services:
  api:
    environment:
      <<: *kaveo-extra
  worker:
    environment:
      <<: *kaveo-extra

An empty value is fine for a text setting such as a URL or token. For a number, boolean or fixed-choice setting, give the ${NAME:-default} form a real default: an empty value for those stops the api and worker at startup.

Apply both files together:

docker compose --env-file .env -f infra/docker-compose.yml -f compose.override.yml up -d

Pass --env-file explicitly. Recent Compose versions look for .env next to the first compose file, in infra/, rather than in the directory you run the command from. The Make targets accept the same command through their COMPOSE variable:

make up COMPOSE="docker compose --env-file .env -f infra/docker-compose.yml -f compose.override.yml"

These settings need the override:

• Logging, telemetry and capacity: KAVEO_LOG_LEVEL, KAVEO_LOG_FORMAT, KAVEO_TELEMETRY, KAVEO_DB_POOL_MIN, KAVEO_DB_POOL_MAX, KAVEO_SCAN_MAX_CONCURRENCY, KAVEO_ATTACK_PATH_MAX_ROWS, KAVEO_MAX_SCAN_NODES, KAVEO_RATE_LIMIT_PER_MINUTE, KAVEO_WORKER_LEASE_SECONDS, KAVEO_BACKUP_DIR
• Sessions and identity: KAVEO_SESSION_TTL_HOURS, KAVEO_OIDC_*, KAVEO_SAML_*, KAVEO_MFA_SECRET_KEY, KAVEO_MFA_ISSUER, KAVEO_SCIM_TOKEN
• Detection: KAVEO_DETECT_*, KAVEO_KEV_CATALOG_PATH, KAVEO_AWS_DEFAULT_REGION
• AI: KAVEO_XAI_API_KEY, KAVEO_GROK_BASE_URL
• Remediation and integrations: KAVEO_REMEDIATION_EXECUTOR, KAVEO_SLACK_WEBHOOK_URL, KAVEO_GITHUB_REPO, KAVEO_GITHUB_TOKEN, KAVEO_JIRA_*, KAVEO_MAILER, KAVEO_SMTP_*, KAVEO_SES_REGION, KAVEO_MAIL_FROM, KAVEO_PUBLIC_WEB_URL
• Other clouds: the variable named by each Azure, GCP, Kubernetes or GitHub account's env:NAME credential reference. See Connect cloud accounts.

Required before first start#

Compose refuses to start until POSTGRES_PASSWORD, POSTGRES_APP_PASSWORD and KAVEO_BOOTSTRAP_PASSWORD are set. Generate each one separately:

openssl rand -hex 24

Set KAVEO_SESSION_COOKIE_SECURE explicitly as well: true when Caddy serves TLS, false only for a plain-HTTP bring-up. Compose passes an empty value when it is unset, and the api and worker do not start with an empty value. The .env.example file leaves it empty, so fill it in when you copy that file.

Variable reference#

"Set by compose" means the stock compose file fills the value in. Rows marked "Needs an override" follow the rule above.

Core and database#

Bootstrap and access#

Scanning and detection#

AI#

Feature flags#

Agent investigation, the patrol, the MCP server and the AWS remediation executor are off until you turn them on. The last three rows cover deployment mode, telemetry and billing.

SSO and identity#

Social sign-in callbacks follow the pattern {KAVEO_PUBLIC_ORIGIN}/v1/auth/{provider}/callback, where the provider is google, microsoft or github.

Integrations#

Every setting in this table needs an override.

Per-organization alert channels are managed in the console under Settings → Alerts, not through the environment. See MCP server and integrations.

Production checklist#

Set these before kaveo is reachable by anyone else:

• Serve over TLS. Set KAVEO_SITE_ADDRESS to your hostname, KAVEO_PUBLIC_ORIGIN to the matching https:// origin, KAVEO_SESSION_COOKIE_SECURE=true, and keep KAVEO_ENVIRONMENT=prod.
• Use unique random values for the three required secrets, and keep .env out of source control.
• Set KAVEO_BOOTSTRAP_EMAIL to an address you control before the first start.
• Keep KAVEO_APPROVAL_REQUIRED=true and KAVEO_SIGNUP_ENABLED=false unless you intend to open sign-up.
• Use KAVEO_SCAN_MODE=aws for real accounts, so a failed role assumption fails the scan instead of falling back to synthetic data.
• Set a long random KAVEO_MFA_SECRET_KEY before anyone enrolls in MFA.
• Keep KAVEO_REMEDIATION_EXECUTOR=offline until the separate write role is deployed and reviewed. See Remediation and autonomous patrol.
• Keep tokens and webhook URLs in the environment only, and scope KAVEO_GITHUB_TOKEN to the one repository it writes to.

Related pages#

• Quick start: bring the stack up for the first time.
• Deployment: TLS, routes, backups and air-gapped installs.
• Connect cloud accounts: the read-only role and the other clouds' credential references.
• Security model: what these settings protect and why.
• Evidence and grounded AI: how the AI providers are used and constrained.