---
title: "Run Workloads"
url: "https://docs.caracal.run/v1.0/runtime-console/runtime/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/runtime-console/runtime.md"
description: "Launch a command with one-time credential injection and understand approvals, expiry, signals, and exit behavior."
page_type: "workflow"
concepts: []
requires: []
---

# Run Workloads

Canonical URL: https://docs.caracal.run/v1.0/runtime-console/runtime/
Markdown URL: https://docs.caracal.run/markdown/v1.0/runtime-console/runtime.md
Description: Launch a command with one-time credential injection and understand approvals, expiry, signals, and exit behavior.
Page type: workflow
Concepts: none
Requires: none

---

`caracal run` authenticates a Launcher workload, fetches its bindings, obtains each binding's provider credential after a policy decision, injects the credentials into a child environment, and returns the child's result. The workload identity and bindings come from [Configure Workloads](/v1.0/runtime-console/config-file/); this page is the launch contract - what happens at spawn, and how approvals, expiry, signals, and exits behave.

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

Use `--` before a child command that accepts flags.

## What Happens Before Spawn

```text
workload proof → fetch bindings → obtain provider credentials → inject environment → spawn child
```

For each binding, the runtime validates the environment name and secret-file permissions, then requests the credential for only the configured resource and scopes. The injected value is the resource provider's own credential - a brokered OAuth token or the sealed static key - released only when the provider allows runtime injection and policy approves; the eligible provider kinds are listed in [What a Binding Injects](/v1.0/guides/runtime-run/#what-a-binding-injects). A required failure prevents the child from starting. Optional bindings follow their configured unavailable behavior.

Static upstream credentials such as API keys remain as powerful as the upstream value itself even when the Caracal release decision was scope-bounded. Prefer short-lived provider tokens or Gateway brokering where supported.

## Approval Holds

If STS returns `interaction_required`, the runtime prints an `approval_required` notice containing the hold and binding, long-polls the hold, and retries the credential request once after approval. When the response has no usable expiry, it uses a five-minute fallback. Rejection, expiry, timeout, or consumption by another request prevents spawn.

An operator can inspect eligible holds in the console **Approvals** page. Holds reserved for the Federated user are visible there but can be decided only by the application's own user.

## Child Environment

The child receives configured credential variables and, when the provider reports expiry, `<ENV>_EXPIRES_AT` in epoch seconds. It also receives a narrow allowlist of ordinary process variables such as `PATH`, home, temporary-directory, locale, terminal, CI, environment name, and OS system variables.

Launcher configuration variables are removed. In particular, `CARACAL_WORKLOAD_SECRET`, admin credentials, and most `CARACAL_*` values do not propagate. `CARACAL_ENV` is retained because it identifies the deployment environment.

## Credential Lifetime

`caracal run` obtains credentials once at startup and does not renew them. Use it for bounded processes whose work completes before the injected credentials expire. Use a Caracal SDK when a service must re-exchange credentials, manage Sessions, or continue indefinitely.

Every manifest fetch and credential release is correlated in audit. Rotating the workload secret blocks later launches that still use the prior value. Revoking Caracal authority does not recall a credential that was already injected: a static provider key remains valid until rotated at the provider, and a brokered token until its own expiry.

## Signals and Exit Results

The runtime forwards `SIGINT`, `SIGTERM`, `SIGHUP`, and `SIGQUIT`, waits for the child, and does not leave it running.

| Exit result     | Meaning                                                               |
| --------------- | --------------------------------------------------------------------- |
| Child exit code | The child started and its result is returned unchanged.               |
| `1`             | Configuration, exchange, validation, or Approval failed before spawn. |
| `127`           | The command could not be spawned.                                     |
| `128 + N`       | The child ended because of signal number `N`.                         |

## Next Step

[Inspect Diagnostics and Audit](/v1.0/runtime-console/observability/).