Overview

Caracal gives AI agents and automated workflows short-lived, policy-approved authority instead of long-lived provider credentials in code or environment files. An agent asks for scoped authority when it acts, policy decides before the action reaches a resource, the Gateway or a verified service enforces the result, and audit records what happened.

Use this section when you want the fastest path from a clean machine to a real protected call.

Should You Use Caracal?

Caracal fits when agents, services, or automation need to call APIs, tools, SaaS providers, or data systems without directly holding the upstream credential.

Question	Use Caracal when
Do agents need credentials?	Agents need scoped access to tools, APIs, providers, or data.
Do you need policy before execution?	Access must be allowed or denied before the protected action happens.
Do you need revocation?	Active authority must end centrally without restarting every workload.
Do you need audit evidence?	You need to explain which app, run, policy, resource, and result were involved.

Caracal is not an LLM framework, prompt router, agent scheduler, static config store, general API gateway, or identity provider. If you only have human users behind a normal login, start with an IdP instead.

Managed option

This section covers the self-hosted open-source edition. If you want managed multi-tenancy, hosted management, SSO, or a supported enterprise deployment, see Compare Editions.

First Success Path

flowchart LR
  Install[Install Caracal]
  Stack[Start local stack]
  Setup[Create protected resource]
  Run[Run workload]
  Gateway[Call Gateway]
  Audit[Inspect audit]

  Install --> Stack --> Setup --> Run --> Gateway --> Audit

The onboarding path keeps runtime lifecycle in the caracal CLI and product management in the web console:

1. Install caracal.
2. Start the local stack with caracal up.
3. Sign in to the web console at http://localhost:3001 and complete onboarding to create your first zone.
4. Use guided setup to create an agent app, resource, and active policy.
5. Configure runtime access with environment variables or a caracal.toml profile.
6. Run a workload with caracal run -- or an SDK.
7. Call the protected resource through the Gateway.
8. Inspect Audit in the web console.

Core Terms

Term	Meaning
Agent app	The registered workload identity that asks Caracal for authority.
Agent session	One tracked execution of an agent app.
Resource	The protected API, tool, provider, service, or data target.
Policy	The rules that allow or deny requested resource scopes.
Mandate	The short-lived signed token Caracal issues after policy allows access.
Gateway	The default boundary that verifies mandates, routes requests, brokers provider credentials when needed, and records action-result audit.
Audit	The decision and result trail for authorization, execution, revocation, and diagnostics.

You can finish Get Started with only these terms. Use Concepts when you need the deeper authority, delegation, revocation, and audit model.

Choose Your Next Path

Goal	Start here	You will have
Evaluate Caracal locally	Install Caracal	A verified runtime CLI, packaged local web console, and Docker prerequisite.
Protect one resource end to end	First Protected Call	A Gateway-routed resource, active policy, runtime configuration, and audit explanation.
Add Caracal to app code	Add SDK to Your App	TypeScript, Python, or Go code that opens an agent session and calls the Gateway.
Fix a blocked first run	First-Run Troubleshooting	A focused checklist for readiness, profile, STS, Gateway, upstream, and audit issues.
Learn the full model	Caracal Mental Model	The canonical concept path after first success.
Develop Caracal itself	Set Up Locally	A source-tree development stack and contributor workflow.

Next Step

Continue with Install Caracal.