> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/deployment/configuration.md). # 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` | `stdout` | 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_LOCATION` | unset (inherit trace sink) | WHERE incidents go. Same vocabulary as `KV_LOG_LOCATION`. Unset inherits the trace sink, using the `…/api/v1/incidents` path for the `kv` format. | | `KV_INCIDENT_FORMAT` | unset (inherit `KV_LOG_FORMAT`) | HOW incidents are formatted: `kv`, `json`, or `otlp` (a standalone `kyvvu.incident` span). | ### Behaviour | Env var | Default | Description | | ---------------------- | ------------ | ----------------------------------------------------------------------------------------------- | | `KV_ENVIRONMENT` | `production` | 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()`. | | `KV_SWEEP_ENABLED` | `true` | Whether the background sweeper thread starts automatically. Set `false` to call `sweep_stale_tasks()` manually. | | `KV_SWEEP_INTERVAL_SECONDS` | `300` | How often the background sweeper runs (seconds). | | `KV_SWEEP_FLUSH_ON_EVICT` | `true` | Whether to attempt a batch log post for evicted tasks before discarding their buffers. | ### 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` | `INFO` | 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` | `noreply@kyvvu.com` | 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: ```bash 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: ```bash KV_SMTP_HOST=email-smtp.eu-central-1.amazonaws.com KV_SMTP_PORT=587 KV_SMTP_USER= KV_SMTP_PASSWORD= KV_SMTP_FROM=noreply@kyvvu.com 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](https://github.com/Kyvvu/platform/blob/main/docs/deployment/self-hosted.md) — deployment guide * [Architecture](/core-concepts/architecture.md) — how components use these settings --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kyvvu.com/deployment/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.