Run an Agent with caracal run

caracal run starts a local subprocess with Caracal runtime environment variables and profile-backed credentials. Use it for development, demos, and controlled local runs.

Prepare a profile

Run caracal up.
Open caracal console.
Select guided setup.
Fill in the upstream URL, resource identifier, runtime profile, profile path, secret file, and first request path.
Enable write profile files.
Save the generated profile and secret file.

The generated profile is the source for SDK client constructors and caracal run.

Run a command

caracal run -- npm start

The child process receives the Caracal variables needed to locate the profile, exchange credentials, and route configured resources through the Gateway.

Validate the run

Check	Command or surface
Runtime is ready	`caracal status --ready`
Profile is readable	`caracal run — env
First request succeeds	Use the guided setup first request path.
Audit captured the request	Console `audit` or `request trace`.

Troubleshooting

Symptom	Fix
SDK cannot find config	Confirm `CARACAL_CONFIG` points to the generated profile.
Secret file rejected	Restrict file permissions and avoid setting both inline and file secrets.
Gateway routing misses the resource	Confirm resource bindings and upstream prefixes in the profile.
Request denied	Check policy-set activation, scopes, and audit diagnostics.