Run Workloads

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; this page is the launch contract - what happens at spawn, and how approvals, expiry, signals, and exits behave.

caracal run -- python3 agent.py

Use -- before a child command that accepts flags.

What Happens Before Spawn

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