--- title: "Guides" url: "https://docs.caracal.run/v1.0/guides/" markdown_url: "https://docs.caracal.run/markdown/v1.0/guides.md" description: "Task-focused implementation guides for modeling, authorizing, integrating, protecting, operating, and extending Caracal." page_type: "page" concepts: [] requires: [] --- # Guides Canonical URL: https://docs.caracal.run/v1.0/guides/ Markdown URL: https://docs.caracal.run/markdown/v1.0/guides.md Description: Task-focused implementation guides for modeling, authorizing, integrating, protecting, operating, and extending Caracal. Page type: page Concepts: none Requires: none --- Use Guides after [Get Started](/v1.0/get-started/) when you have a concrete integration job. These pages teach complete application-integrator and resource-server workflows; package and API pages remain the source for signatures and wire fields. ## When to use this section * **Application integrators** start with an SDK guide, then route outbound calls through Gateway or `caracal run`. * **Resource-server integrators** start with Gateway routing or the adapter matching their server framework. * **Platform integrators** use the modeling, resource/provider, policy, testing, and audit workflows before production traffic. ## Choose by Task | Task | Start with | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Map your architecture onto Caracal | [Model Your Application in Caracal](/v1.0/guides/modeling-recipes/) | | Serve many of your own customers from one deployment | [Serve Your Own Customers](/v1.0/guides/serve-customers/) | | Define protected targets and upstream credentials | [Define Resources and Providers](/v1.0/guides/resources-providers/) and [Provider Recipes](/v1.0/guides/provider-recipes/) | | Write and activate authorization logic | [Author Policy Data](/v1.0/guides/author-policy/) and [Activate a Policy Set](/v1.0/guides/activate-policy-set/) | | Debug an authorization result | [Debug Authorization Decisions](/v1.0/guides/authorize-access/) | | Add Caracal to app code | [TypeScript SDK](/v1.0/guides/sdk-typescript/), [Python SDK](/v1.0/guides/sdk-python/), or [Go SDK](/v1.0/guides/sdk-go/) | | Run an existing process with Caracal tokens | [Run an Agent with caracal run](/v1.0/guides/runtime-run/) | | Protect a Gateway-routed HTTP upstream | [Protect a Gateway-Routed HTTP API](/v1.0/guides/protect-gateway-http/) | | Protect a resource server in process | [Express](/v1.0/guides/protect-express/), [FastAPI](/v1.0/guides/protect-fastapi/), [FastMCP](/v1.0/guides/protect-fastmcp/), [Go net/http](/v1.0/guides/protect-nethttp/), or [MCP server](/v1.0/guides/protect-mcp/) | | Add Delegation, audit export, or Approval | [Delegation](/v1.0/guides/delegation/), [Audit Stream](/v1.0/guides/audit-stream/), or [Human Approval](/v1.0/guides/human-approval/) | | Notify approvers when a hold is raised | [Approval Notifications](/v1.0/guides/approval-notifications/) | | Make retries safe for side-effecting actions | [Safe Retries and Idempotency](/v1.0/guides/idempotency/) | | Test an integration without a live stack | [Test Caracal Integrations](/v1.0/guides/testing/) | | Govern LangChain, LangGraph, or CrewAI | [Govern Agent Frameworks](/v1.0/guides/frameworks/) | | Plan a production integration | [Production Integration Patterns](/v1.0/guides/production-patterns/) | ## Recommended Order ```mermaid 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`, `allowlist`, and `run` | Local runtime lifecycle, Console sign-in admission, 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 adapters | 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](/v1.0/get-started/first-protected-call/) creates that baseline. ## Expected Outcome After following one path through the table, an allowed call reaches exactly one protected resource, a denied call fails before protected work runs, and both outcomes can be found by request ID in **Audit**. :::caution[Common mistake] Use the linked [SDK and package reference](/v1.0/sdks/) for exact release signatures. Guides own sequencing, boundary choices, validation, and recovery - not duplicate API catalogs. ::: ## Next Step Choose the first unfinished job in **Choose by Task**. For a new integration, start with [Model Your Application in Caracal](/v1.0/guides/modeling-recipes/).