---
title: "Run Workloads"
url: "https://docs.caracal.run/runtime-console/runtime/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/runtime.md"
description: "Use caracal run to inject scoped resource tokens into subprocesses."
page_type: "reference"
concepts: []
requires: []
---

# Run Workloads

Canonical URL: https://docs.caracal.run/runtime-console/runtime/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/runtime.md
Description: Use caracal run to inject scoped resource tokens into subprocesses.
Page type: reference
Concepts: none
Requires: none

---

`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.

```bash
caracal run -- python3 agent.py
```

Use `--` when the child command accepts flags.

## Execution Flow

```text
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

```toml
[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](/runtime-console/admin/) for ongoing Console work after the workload path is running.