---
title: "Configuration Keys"
url: "https://docs.caracal.run/reference/configuration/"
markdown_url: "https://docs.caracal.run/markdown/reference/configuration.md"
description: "Runtime profile, service environment, and deployment configuration keys."
page_type: "config"
concepts: []
requires: []
---

# Configuration Keys

Canonical URL: https://docs.caracal.run/reference/configuration/
Markdown URL: https://docs.caracal.run/markdown/reference/configuration.md
Description: Runtime profile, service environment, and deployment configuration keys.
Page type: config
Concepts: none
Requires: none

---

Caracal has three configuration domains:

| Domain | Used by | Choose it when |
| --- | --- | --- |
| Runtime workload config | `caracal run` and SDK clients. | A workload needs Caracal-issued resource credentials. |
| Service environment config | API, STS, Gateway, Audit, Coordinator, and Control. | A service needs URLs, secrets, limits, or readiness settings. |
| Deployment values | Helm, Compose, Postgres, and Redis. | Operators size, schedule, expose, or secure infrastructure. |

```mermaid
flowchart TD
  Need{What are you configuring?}
  Need -->|workload credentials| Runtime[Runtime profile and CARACAL_CONFIG]
  Need -->|service behavior| Env[Service environment variables]
  Need -->|deployment shape| Deploy[Helm values or Compose files]
  Runtime --> Precedence[Config precedence reference]
  Env --> Ops[Environment variables reference]
  Deploy --> Platform[Operations deployment pages]
```

## Runtime Profile Fields

| Field | Meaning |
| --- | --- |
| `zone_url` | Cloud/custom STS URL override for token exchange. |
| `sts_url` | Cloud/custom SDK-readable STS alias/fallback. |
| `coordinator_url` | Cloud/custom SDK/Console Coordinator URL override. |
| `gateway_url` | Cloud/custom Gateway URL override for SDK transports. |
| `zone_id` | Zone identifier. |
| `application_id` | Confidential application ID. |
| `app_client_secret_file` | Cloud/custom secret-file path override. |
| `app_client_secret` | Inline local-development secret. |
| `ttl_seconds` | `caracal run` exchange TTL, capped at 900 seconds. |
| `continue_on_failure` | Required credential failure behavior. |
| `credentials[]` | Required resource credentials. |
| `optional_credentials[]` | Optional resource credentials with `on_failure`. |
| `mcp_governance.mode` | `block` or `log` for likely MCP subprocesses. |

Credential entries use `env`, `resource`, optional `upstream_prefix`, and optional `credential_type`. Use `provider_token` for direct `caracal run` provider-key injection and `caracal_mandate` for mandate-aware workloads.

Local dev and stable runtime launches auto-detect the client secret and
credential manifest from the OS Caracal config directory. Use explicit
secret-file paths and service URLs only for cloud deployments, containers, or
custom infrastructure.

## Core Service Environment Keys

| Key | Services |
| --- | --- |
| `CARACAL_MODE` | All services. |
| `DATABASE_URL` / `DATABASE_URL_FILE` | API, STS, Gateway, Audit, Coordinator. |
| `REDIS_URL` / `REDIS_URL_FILE` | API, STS, Gateway, Audit, Coordinator. |
| `STREAMS_HMAC_KEY` / `STREAMS_HMAC_KEY_FILE` | Stream producers and consumers. |
| `AUDIT_HMAC_KEY` / `AUDIT_HMAC_KEY_FILE` | Audit producers and Audit service. |
| `GATEWAY_STS_HMAC_KEY` / `GATEWAY_STS_HMAC_KEY_FILE` | API, STS, Gateway. |
| `ZONE_KEK` / `ZONE_KEK_FILE` | API and STS. |
| `CARACAL_ADMIN_TOKEN` / `CARACAL_ADMIN_TOKEN_FILE` | API and management clients. |
| `CARACAL_COORDINATOR_TOKEN` / `CARACAL_COORDINATOR_TOKEN_FILE` | Coordinator and Console agent/delegation views. |

## Deployment Values

Helm values live under `infra/helm/caracal/values.yaml`. Compose environment and secrets are defined by `infra/docker/docker-compose.yml` and `infra/docker/runtime-compose.yml`.

## Next Step

Use [Configuration Order](/reference/config-precedence/) to understand which file, environment variable, or deployment value wins.

## Related Pages

- [Configure Workloads](/runtime-console/config-file/)
- [Configure Service Environment](/operations/env-vars/)
- [Choose a Cloud Profile](/operations/cloud-native-profiles/)