Guides

Use Guides after Get Started or the Tutorials when you know the task you need to complete. You do not need to read every concept first; each guide links to the canonical concept page when the model matters.

Choose by Task

Task	Start with
Map your architecture onto Caracal	Model Your Application in Caracal
Serve many of your own customers from one deployment	Serve Your Own Customers
Define protected targets and upstream credentials	Define Resources and Providers and Provider Recipes
Write and activate authorization logic	Author Policy Data and Activate a Policy Set
Debug an authorization result	Debug Authorization Decisions
Add Caracal to app code	TypeScript SDK, Python SDK, or Go SDK
Run an existing process with Caracal tokens	Run an Agent with caracal run
Protect a Gateway-routed HTTP upstream	Protect a Gateway-Routed HTTP API
Protect a resource server in process	Express, FastAPI, FastMCP, Go net/http, or MCP server
Add delegation, audit export, or step-up	Delegation, Audit Stream, or Step-Up Re-Authentication
Plan a production integration	Production Integration Patterns

Recommended Order

flowchart LR
  Model["Model app"]
  Resource["Define resources and providers"]
  Policy["Author policy"]
  Activate["Activate policy"]
  App["Integrate app"]
  Protect["Protect boundary"]
  Debug["Trace and debug"]

  Model --> Resource --> Policy --> Activate --> App --> Protect --> Debug

Surface Boundaries

Use the right surface for each task:

Surface	Use for
caracal up, down, status, upgrade, purge, run, web	Local runtime lifecycle and subprocess injection.
Console	Human-facing zone, application, provider, resource, policy, session, audit, explanation, delegation, and diagnostic workflows.
Admin API and @caracalai/admin	Automation for the same control-plane objects.
SDKs and connectors	Application integration, context propagation, mandate exchange, and mandate verification.

Before You Start

You need a running Caracal runtime, a zone, an application, at least one resource, and an active policy set. First Protected Call creates that baseline.