---
title: "Configuration Order"
url: "https://docs.caracal.run/reference/config-precedence/"
markdown_url: "https://docs.caracal.run/markdown/reference/config-precedence.md"
description: "How Caracal chooses runtime profiles, environment values, file secrets, and deployment values."
page_type: "config"
concepts: []
requires: []
---

# Configuration Order

Canonical URL: https://docs.caracal.run/reference/config-precedence/
Markdown URL: https://docs.caracal.run/markdown/reference/config-precedence.md
Description: How Caracal chooses runtime profiles, environment values, file secrets, and deployment values.
Page type: config
Concepts: none
Requires: none

---

## Runtime Workload Config

`caracal run` and SDK loaders use this order:

1. `CARACAL_CONFIG`, when set and the file exists.
2. Environment runtime config.
3. `$XDG_CONFIG_HOME/caracal/caracal.toml`.
4. `~/.config/caracal/caracal.toml`.

The runtime does not read `./caracal.toml` from the current working directory.

## Environment Runtime Config Detection

Environment config is considered when workload identity variables are present.
Local dev and stable launches use `CARACAL_ZONE_ID` and
`CARACAL_APPLICATION_ID`, then auto-detect credential files from the OS Caracal
config directory. Cloud and custom deployments can provide explicit
`CARACAL_APP_CLIENT_SECRET_FILE`, `CARACAL_RUN_CREDENTIALS`,
`CARACAL_RUN_CREDENTIALS_FILE`, or `CARACAL_RESOURCES_FILE` values when mounted
secret or config paths differ from the local convention.

Set only one of `CARACAL_RUN_CREDENTIALS` and `CARACAL_RUN_CREDENTIALS_FILE`.

Resource bindings resolve from profile credentials, then
`CARACAL_RESOURCES_FILE`, then `CARACAL_RESOURCES`. Later bindings with the
same resource ID override earlier bindings, so a short environment override can
replace one entry from a mounted JSON file without duplicating the file.

## File-Secret Resolution

Services support `*_FILE` variants for configured secret keys. File values are resolved before validation so deployment templates can mount secrets instead of placing sensitive material directly in environment variables.

## Deployment Values

| Deployment path | Precedence model |
| --- | --- |
| Docker Compose | Shell environment overrides defaults in compose files; secrets are mounted from files. |
| Helm | CLI `--set` and later values files override earlier chart values; runtime Secret keys feed mounted service env. |
| Console generated profile | Explicit values from guided setup write a profile and secret file when file writing is enabled. |

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Expected profile is ignored | `CARACAL_CONFIG` may point elsewhere or environment runtime config may be winning. |
| Service fails with missing secret | Confirm the `*_FILE` variable name is supported by that service and the file is readable. |
| Helm values render unexpected defaults | Check values file order and CLI overrides. |

## Next Step

Use [Defaults and Limits](/reference/defaults-and-limits/) to confirm ports, TTLs, request limits, and stream defaults.