Configure Workloads

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:

<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

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 when the profile is ready and you need to inject scoped credentials into a process.