# 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. |

### Endpoints

| Env var                | Default          | Description                                                                         |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `KV_LOG_ENDPOINT`      | `stdout`         | URL for batch log flush, `stdout` for JSON-line output, or empty string to disable. |
| `KV_INCIDENT_ENDPOINT` | unset (disabled) | URL for incident webhooks, or `stdout` for JSON-line output.                        |

### 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. |

***

## 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: 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:

```
GET https://docs.kyvvu.com/deployment/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.