Configuration Reference

What you'll learn: All environment variables for the SDK, engine, and platform API.

---

SDK / Engine configuration

Precedence (highest to lowest): explicit kwargs > environment variables > .env in cwd > built-in defaults.

Authentication and identity

Env var	Default	Description
KV_API_URL	https://platform.kyvvu.com	Base URL of the Kyvvu platform API.
KV_API_KEY	--	Bearer API key (KvKey-...). Required for policy fetch.
KV_AGENT_KEY	--	Stable agent identifier used to fetch policies.
KV_INSTANCE_ID	auto-generated	Identifier for this runner instance. A random suffix is appended to prevent collisions.

Log output

Env var	Default	Description
KV_LOG_LOCATION	unset	WHERE logs go. URL → HTTP POST, file path → JSONL, stdout → terminal, none/empty → disabled.
KV_LOG_FORMAT	kv	HOW logs are formatted: kv (Kyvvu batch API), json, or otlp.
KV_INCIDENT_ENDPOINT	unset (disabled)	URL for incident webhooks, or stdout for JSON-line output.

Legacy: KV_LOG_ENDPOINT and KV_LOG_EXPORTERS are still supported. Priority: KV_LOG_LOCATION > KV_LOG_EXPORTERS > KV_LOG_ENDPOINT.

Behaviour

Env var	Default	Description
KV_ENV	production (engine) / development (SDK)	Forwarded to EvalContext.environment.
KV_LOG_PAYLOADS	full	full includes step input/output in logs. metadata_only redacts content but preserves shape.
KV_TEMPLATE_LOCATION	built-in	Path to a custom YAML behaviour template.

Cache and limits

Env var	Default	Description
KV_POLICY_TTL_SECONDS	300	How long to cache fetched policies (seconds).
KV_HTTP_TIMEOUT_SECONDS	10	Per-request HTTP timeout.
KV_TASK_MAX_AGE_SECONDS	3600	Abandoned-task eviction threshold for sweep_stale_tasks().

Resilience (opt-in)

Env var	Default	Description
KV_POLICY_FAIL_MODE	open	open = allow all when no policies loaded. closed = block all step_execution behaviors when no policies are available.
KV_POLICY_CACHE_PATH	empty (disabled)	File path for on-disk policy cache. Written after each successful fetch; loaded on cold start if the API is unreachable.
KV_POLICY_CACHE_MAX_AGE_SECONDS	86400	Maximum age (seconds) of the disk cache before a staleness warning is emitted. The cache is still used when stale.
KV_POLICY_HMAC_SECRET	empty (disabled)	Shared secret for HMAC-SHA256 verification of policy fetch responses. Must be set on both the engine and API for signing to activate.
KV_REGISTRATION_TTL	empty (infinite)	How long a cached agent registration is valid before re-registering. Accepts 30m, 24h, 7d, or raw seconds. Empty = cache never expires (re-registration only on payload change).

Logging

Env var	Default	Description
KV_LOG_LEVEL	WARNING	Log level for kyvvu / kyvvu_engine Python loggers. Set to DEBUG for per-evaluation traces.

---

Email (password reset)

Password reset emails are sent via SMTP. In development, no SMTP configuration is needed — the reset URL is logged to the API console instead.

Env var	Default	Description
KV_SMTP_HOST	empty	SMTP server hostname. When empty, reset URLs are logged instead of emailed.
KV_SMTP_PORT	587	SMTP server port (TLS).
KV_SMTP_USER	empty	SMTP authentication username.
KV_SMTP_PASSWORD	empty	SMTP authentication password.
KV_SMTP_FROM	[e-mail]	Sender email address.
KV_WEB_URL	http://localhost:3000	Dashboard URL used in reset email links.

Production setup (AWS SES)

SES is provisioned via Terraform:

cd infra/terraform
terraform apply          # creates SES domain, DKIM, SMTP user
terraform output ses_smtp_password   # copy this (sensitive)
terraform output ses_smtp_username   # copy this

Then set in the EC2 .env file:

KV_SMTP_HOST=email-smtp.eu-central-1.amazonaws.com
KV_SMTP_PORT=587
KV_SMTP_USER=<ses_smtp_username output>
KV_SMTP_PASSWORD=<ses_smtp_password output>
KV_SMTP_FROM=[e-mail]
KV_WEB_URL=https://platform.kyvvu.com

Note: New SES accounts start in sandbox mode. Request production access via AWS Console → SES → Account dashboard.

---

Next steps

• Self-Hosted Setup — deployment guide

• Architecture — how components use these settings