Guides
Each guide covers one end-to-end workflow. Start from the guide that matches your current task. Prerequisites are listed at the top of each guide.
Section map
Section titled “Section map”| Guide | What it covers |
|---|---|
| Integrate the TypeScript SDK | Install @caracalai/sdk, configure env vars, spawn agents, delegate authority, and make outbound calls |
| Integrate the Python SDK | Install caracalai-sdk, use async context managers to spawn and delegate, wire ASGI middleware |
| Integrate the Go SDK | Install github.com/garudex-labs/caracal/sdk, use Spawn, Delegate, Current, and Transport |
| Protect an MCP Server | Gate MCP tool calls with mandate verification using @caracalai/transport-mcp (TS) or caracalai_transport_mcp (Python) |
| Protect an Express App | Add caracalAuth middleware to Express routes and enforce scope requirements |
| Protect a FastMCP App | Attach CaracalAuth to a FastMCP server so every tool call is mandate-gated |
| Protect a Go net/http Service | Wrap Go handlers with mcpnethttp.Middleware and read validated claims from context |
| Author a Rego Policy | Write a caracal.authz policy, understand the full input schema, and avoid forbidden builtins |
| Activate a Policy Set | Create, version, bundle, and promote a policy set to active using the CLI |
| Define Resources and Providers | Register upstream resources, declare scopes, and attach credential providers |
| Issue Grants and Invitations | Bind applications and users to resource scopes; invite new zone members |
| Implement Multi-Agent Delegation | Spawn child agents, attach caveats, read the delegation graph, and trigger cascade revocation |
| Tail and Query the Audit Stream | Stream live decisions from the CLI and inspect full diagnostics per request |
Run an Agent with caracal run | Inject a short-lived per-resource token into a subprocess without writing SDK code |
| Step-Up Re-Authentication | Handle interaction_required from the STS and complete the challenge flow from agent code |
Prerequisites shared across all guides
Section titled “Prerequisites shared across all guides”- A running Caracal stack (
caracal upor Docker Compose). - A zone with at least one registered application. Run
caracal initon a fresh stack to create the local zone and writecaracal.toml. CARACAL_ADMIN_TOKENset in your shell for CLI operations that mutate control-plane state.