---
title: "Run an Agent with caracal run"
url: "https://docs.caracal.run/guides/runtime-run/"
markdown_url: "https://docs.caracal.run/markdown/guides/runtime-run.md"
description: "Use a generated runtime profile to inject scoped Caracal access into a subprocess."
page_type: "page"
concepts: []
requires: []
---

# Run an Agent with caracal run

Canonical URL: https://docs.caracal.run/guides/runtime-run/
Markdown URL: https://docs.caracal.run/markdown/guides/runtime-run.md
Description: Use a generated runtime profile to inject scoped Caracal access into a subprocess.
Page type: page
Concepts: none
Requires: none

---

`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

1. Run `caracal up`.
2. Open `caracal console`.
3. Select `guided setup`.
4. Fill in the upstream URL, resource identifier, runtime profile, profile path, secret file, and first request path.
5. Enable **write profile files**.
6. Save the generated profile and secret file.

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

## Run a command

```bash
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 | grep CARACAL` |
| 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. |

Related pages: [First Protected Call](/get-started/first-protected-call/), [Add SDK to Your App](/get-started/add-sdk-to-your-app/), and [Audit and Request Traces](/concepts/audit-ledger/).