---
title: "Configure Workloads"
url: "https://docs.caracal.run/runtime-console/config-file/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/config-file.md"
description: "Configure runtime profiles, credential manifests, secret files, and workload service endpoints."
page_type: "config"
concepts: []
requires: []
---

# Configure Workloads

Canonical URL: https://docs.caracal.run/runtime-console/config-file/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/config-file.md
Description: Configure runtime profiles, credential manifests, secret files, and workload service endpoints.
Page type: config
Concepts: none
Requires: none

---

Runtime config is workload input for `caracal run` and SDK credential loaders. It is not Console state and it does not create, select, or manage zones.

## Source Precedence

| Order | Source |
| --- | --- |
| 1 | `CARACAL_CONFIG`, when set and the file exists. |
| 2 | Environment runtime config. |
| 3 | `$XDG_CONFIG_HOME/caracal/caracal.toml` or `~/.config/caracal/caracal.toml`. |

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

## Environment Config

| Variable | Meaning |
| --- | --- |
| `CARACAL_STS_URL` or `CARACAL_ZONE_URL` | Cloud/custom STS URL override for token exchange. |
| `CARACAL_GATEWAY_URL` | Cloud/custom Gateway URL override used by SDK transports. |
| `CARACAL_COORDINATOR_URL` | Cloud/custom Coordinator URL override used by SDKs and Console agent views. |
| `CARACAL_ZONE_ID` | Zone identifier. |
| `CARACAL_APPLICATION_ID` | Confidential application identifier. |
| `CARACAL_APP_CLIENT_SECRET_FILE` | Cloud/custom path to a mounted client-secret file. |
| `CARACAL_APP_CLIENT_SECRET` | Inline local-development client secret. |
| `CARACAL_RUN_CREDENTIALS_FILE` | Cloud/custom JSON credential manifest file. |
| `CARACAL_RUN_CREDENTIALS` | Inline JSON credential manifest. |
| `CARACAL_RUN_CONTINUE_ON_FAILURE` | `true` or `false` for required credential failure behavior. |
| `CARACAL_RUN_TTL_SECONDS` | Credential exchange TTL, capped at 900 seconds. |
| `CARACAL_MCP_GOVERNANCE_MODE` | `block` or `log`. |

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

Local dev and stable runtime launches normally set only `CARACAL_ZONE_ID` and
`CARACAL_APPLICATION_ID`. The runtime and SDKs auto-detect the client secret and
credential manifest from the OS Caracal config directory:

```text
<Caracal config dir>/runtime/<zone_id>/<application_id>/client-secret
<Caracal config dir>/runtime/<zone_id>/<application_id>/credentials.json
```

Local dev and stable service URLs also resolve automatically. Set service URL
overrides only for cloud deployments, containers, or custom service locations.

## TOML Schema

```toml
zone_id = "zone_prod"
application_id = "app_agent"
ttl_seconds = 900

[[credentials]]
env = "OPENAI_API_KEY"
resource = "resource://openai"
credential_type = "provider_token"
upstream_prefix = "https://api.openai.com/v1"

[[optional_credentials]]
env = "CARACAL_MANDATE"
resource = "resource://mandate-aware-api"
credential_type = "caracal_mandate"
on_failure = "warn"

[mcp_governance]
mode = "block"
```

## Field Reference

| Field | Meaning |
| --- | --- |
| `zone_url` | Cloud/custom STS URL override used by `caracal run`; `sts_url` is accepted as an SDK-readable alias/fallback. |
| `gateway_url` | Cloud/custom Gateway endpoint override for SDK transports. |
| `coordinator_url` | Cloud/custom Coordinator endpoint override for SDK agent/delegation features. |
| `zone_id` | Zone created in Console. |
| `application_id` | Confidential application used by the workload. |
| `app_client_secret_file` | Cloud/custom secret-file path override. |
| `app_client_secret` | Inline local-development secret. |
| `ttl_seconds` | Credential exchange TTL; defaults to and is capped at 900 seconds. |
| `continue_on_failure` | Required credential failure behavior; defaults to `false`. |
| `credentials[]` | Required resource tokens. |
| `optional_credentials[]` | Optional resource tokens with `on_failure = "warn"` or `"error"`. |
| `mcp_governance.mode` | `block` or `log` for likely MCP subprocesses. |

Credential entries use `env`, `resource`, optional `upstream_prefix`, and optional `credential_type`. `provider_token` is the `caracal run` golden path and requires a provider with `allow_runtime_injection = true`; `caracal_mandate` is for workloads that consume Caracal mandates directly. SDKs can also use entries as resource audiences and Gateway routing hints.

## Security Rules

- Use auto-detected local credential files for dev and stable runtime launches.
- Use explicit secret-file paths for cloud deployments, containers, or external secret stores.
- Secret files and explicit config files must not be group- or world-writable.
- The default profile path must use owner-only permissions on POSIX systems.
- Non-local insecure `http://` STS URLs are rejected unless explicitly allowed by environment.
- Environment names that affect runtime loading, such as `NODE_OPTIONS`, `LD_PRELOAD`, and dynamic-library path variables, are blocked.

## Cloud and Custom Secret Paths

Cloud deployments, containers, and external secret stores can override the
auto-detected local paths with `CARACAL_APP_CLIENT_SECRET_FILE`,
`CARACAL_RUN_CREDENTIALS_FILE`, or `app_client_secret_file` in a runtime profile.
Use these only when the standard OS Caracal config directory is not the correct
secret location for the workload.

Cloud deployments and custom service locations can also set `CARACAL_STS_URL`,
`CARACAL_GATEWAY_URL`, `CARACAL_COORDINATOR_URL`, `sts_url`, `gateway_url`, or
`coordinator_url`. Do not set these for the default local stack.

## Generated Profiles

Console `guided setup` can generate a complete profile and one-time secret file using real zone, application, provider, resource, policy, and credential values. Enable file writing when you want the Console to write the profile and secret file with owner-only permissions.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `CARACAL_CONFIG` is set but ignored | The file must exist; when it is set, no other profile path is considered. |
| Runtime rejects a profile | Remove unknown fields and check permissions, URL safety, and credential env names. |
| Provider key is not injected | Confirm the credential uses `credential_type = "provider_token"` and the provider config allows runtime injection. |
| SDK Gateway routing does not happen | Confirm `gateway_url` and `upstream_prefix` are present. |
| Optional credential stops the process | Set `on_failure = "warn"` for optional credentials that may be absent. |

## Next Step

Use [Run Workloads](/runtime-console/runtime/) when the profile is ready and you need to inject scoped credentials into a process.