Run Workloads

caracal run is the runtime execution command. It starts a subprocess with scoped Caracal resource tokens in environment variables and returns the subprocess exit code.

caracal run -- python3 agent.py

Use -- when the child command accepts flags.

Execution Flow

runtime config -> MCP governance check -> STS token exchange -> env injection -> child process

1. Load runtime config from environment, CARACAL_CONFIG, or the default XDG profile.
2. Validate config keys, URL safety, secret-file permissions, and credential environment names.
3. Check [mcp_governance] rules before spawning likely MCP server commands.
4. Exchange each required credentials[] entry for a resource token.
5. Exchange each optional_credentials[] entry and apply its on_failure behavior.
6. Spawn the child process without shell: true.
7. Forward stdin, stdout, stderr, and the child exit code.

Injected tokens have a 15-minute TTL from the runtime exchange.

Required Runtime Identity

caracal run needs:

Input	Source
STS/zone URL	Automatic for local dev/stable; explicit only for cloud/custom deployments.
Zone ID	CARACAL_ZONE_ID or zone_id.
Application ID	CARACAL_APPLICATION_ID or application_id.
Client secret	Auto-detected local client-secret file or explicit cloud/custom secret-file config.
Credential manifest	Auto-detected local credential manifest or credentials[] / optional_credentials[] in a profile.

Console guided setup is the recommended way to generate the first profile and one-time client secret file. Local dev and stable launches auto-detect credential files under the OS Caracal config directory after the zone and application IDs are known. Service URLs use local defaults automatically unless cloud/custom deployment docs configure explicit overrides.

Step-Up Challenges

When STS returns interaction_required, the runtime writes the challenge notice, polls the step-up endpoint every two seconds, and retries exchange for up to five minutes. If the challenge is not satisfied in time, the subprocess is not spawned.

Environment Safety

The runtime injects only configured credential environment variables and a small inherited allowlist such as path, home, shell, temporary directory, locale, color, CI, XDG, and Docker-related variables. Credential names that can alter process loading, such as NODE_OPTIONS, LD_PRELOAD, or dynamic-library path variables, are blocked.

MCP governance

[mcp_governance]
mode = "block"

block stops likely MCP server subprocesses before launch. log records the governance event and continues; outside development it requires an explicit platform override.

Troubleshooting

Symptom	Check
runtime config not found	Run Console guided setup, set platform env vars, or point CARACAL_CONFIG at a profile.
Secret-file validation fails	Store the secret value in the file and ensure it is not group- or world-writable.
Token exchange fails	Confirm caracal status --ready, zone ID, application ID, client secret, resource ID, and policy coverage.
Child command never starts	Required credential exchange, step-up, config validation, or MCP governance failed before spawn.
Child command exits non-zero	The runtime returns the child process exit code after successful token injection.

Next Step

Use Manage Product Objects for ongoing Console work after the workload path is running.