# Caracal > Caracal gives agents and automated workloads short-lived, policy-approved authority for protected resources. Caracal is an open-source system built by Garudex Labs. Applications request scoped authority, STS evaluates the active policy set, Gateway or an in-process verifier enforces the issued Mandate, Coordinator owns Sessions and Delegations, and Audit records decisions and outcomes. Subjects and Authority records provide optional external identity attribution and revocation anchors. The runtime includes API (port 3000), STS (port 8080), Gateway (port 8081), Audit (port 9090), and Coordinator (port 4000). Control runs as an optional in-process plugin inside API. Runtime lifecycle uses the top-level caracal runtime CLI; product management uses Console, Admin SDK, or Control API. ## Machine-readable endpoints - [Full Markdown corpus](https://docs.caracal.run/llms-full.txt): Complete documentation content in one text file. - [Page metadata index](https://docs.caracal.run/page-index.json): JSON list of canonical HTML URLs, Markdown URLs, titles, descriptions, concepts, requirements, keywords, aliases, and services. - [Concept graph](https://docs.caracal.run/concept-graph.json): JSON graph of pages, concepts, and requirements. - Per-page Markdown: https://docs.caracal.run/markdown/{page-id}.md, for example https://docs.caracal.run/markdown/guides/serve-customers.md. ## Get Started - [Overview](https://docs.caracal.run/v1.0/get-started/) ([Markdown](https://docs.caracal.run/markdown/v1.0/get-started.md)): Learn what problem Caracal solves and how it works in plain language, then follow the shortest path to your first protected, audited call. - [Install Caracal](https://docs.caracal.run/v1.0/get-started/install-caracal/) ([Markdown](https://docs.caracal.run/markdown/v1.0/get-started/install-caracal.md)): Install the caracal CLI, verify Docker, and start the local stack that the rest of Get Started uses. - [First Protected Call](https://docs.caracal.run/v1.0/get-started/first-protected-call/) ([Markdown](https://docs.caracal.run/markdown/v1.0/get-started/first-protected-call.md)): Give an AI agent short-lived, policy-approved authority to call an LLM provider - without the agent ever holding the provider API key. - [Add SDK to Your App](https://docs.caracal.run/v1.0/get-started/add-sdk-to-your-app/) ([Markdown](https://docs.caracal.run/markdown/v1.0/get-started/add-sdk-to-your-app.md)): Turn the throwaway script from First Protected Call into an application integration with a durable configuration profile. - [First-Run Troubleshooting](https://docs.caracal.run/v1.0/get-started/first-run-troubleshooting/) ([Markdown](https://docs.caracal.run/markdown/v1.0/get-started/first-run-troubleshooting.md)): Fix common install, readiness, sign-in, identity, mandate, Gateway, upstream, and audit issues during onboarding. ## Tutorials - [Tutorials](https://docs.caracal.run/v1.0/tutorials/) ([Markdown](https://docs.caracal.run/markdown/v1.0/tutorials.md)): A guided journey from the Get Started agent flow to a protected real API, identifiable app runs, self-serve debugging, and a chosen production path. - [Protect Your First Real API](https://docs.caracal.run/v1.0/tutorials/protect-an-api/) ([Markdown](https://docs.caracal.run/markdown/v1.0/tutorials/protect-an-api.md)): Protect an HTTP service you own with Caracal, then prove it allows the permitted call and denies everything else. - [Make Runs Identifiable with Labels](https://docs.caracal.run/v1.0/tutorials/connect-an-agent/) ([Markdown](https://docs.caracal.run/markdown/v1.0/tutorials/connect-an-agent.md)): Label the protected calls your code makes so each agent's work is identifiable in the audit trail. - [Trace One Protected Request](https://docs.caracal.run/v1.0/tutorials/inspect-a-run/) ([Markdown](https://docs.caracal.run/markdown/v1.0/tutorials/inspect-a-run.md)): Use the audit trail and decision trace to explain exactly why a request was allowed or denied. - [Choose Your Production Integration Path](https://docs.caracal.run/v1.0/tutorials/choose-production-path/) ([Markdown](https://docs.caracal.run/markdown/v1.0/tutorials/choose-production-path.md)): Pick the one enforcement boundary that matches your deployment, then follow its implementation guide. ## Guides - [Guides](https://docs.caracal.run/v1.0/guides/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides.md)): Task-focused implementation guides for modeling, authorizing, integrating, protecting, operating, and extending Caracal. - [Model Your Application in Caracal](https://docs.caracal.run/v1.0/guides/modeling-recipes/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/modeling-recipes.md)): Map zones, applications, resources, providers, and scopes onto real deployments before creating production objects. - [Serve Your Own Customers](https://docs.caracal.run/v1.0/guides/serve-customers/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/serve-customers.md)): Run one Caracal deployment that serves many of your customers, with per-customer identity, policy, audit, and revocation. - [Define Resources and Providers](https://docs.caracal.run/v1.0/guides/resources-providers/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/resources-providers.md)): Register protected upstream resources and explicit provider auth modes from the web console. - [Provider Recipes](https://docs.caracal.run/v1.0/guides/provider-recipes/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/provider-recipes.md)): Concrete copy-paste provider setups for OpenAI, Anthropic, Google, GitHub, Slack, LiteLLM, Ollama, and internal APIs, with the enforcement boundary and client wiring each one uses. - [Author Policy Data](https://docs.caracal.run/v1.0/guides/author-policy/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/author-policy.md)): Author the grant, binding, and confinement data the platform decision contract reads, and validate it before activation. - [Activate a Policy Set](https://docs.caracal.run/v1.0/guides/activate-policy-set/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/activate-policy-set.md)): Version policies, bundle them into a policy set, simulate the result, and promote the version to active. - [Debug Authorization Decisions](https://docs.caracal.run/v1.0/guides/authorize-access/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/authorize-access.md)): Diagnose denied exchanges, missing scopes, inactive policy sets, stale sessions, resource mismatches, and missing audit evidence. - [Integrate the TypeScript SDK](https://docs.caracal.run/v1.0/guides/sdk-typescript/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/sdk-typescript.md)): Install @caracalai/sdk, load a runtime profile, run governed sessions, delegate authority, and inject Caracal headers. - [Integrate the Python SDK](https://docs.caracal.run/v1.0/guides/sdk-python/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/sdk-python.md)): Install caracalai-sdk, load a runtime profile, run governed sessions with async context managers, delegate authority, and use httpx transport injection. - [Integrate the Go SDK](https://docs.caracal.run/v1.0/guides/sdk-go/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/sdk-go.md)): Install the Go SDK, load a runtime profile, run governed sessions with context.Context, delegate authority, and inject Caracal headers. - [Run an Agent with caracal run](https://docs.caracal.run/v1.0/guides/runtime-run/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/runtime-run.md)): Launch a workload with console-managed credential bindings injected as environment variables. - [Protect a Gateway-Routed HTTP API](https://docs.caracal.run/v1.0/guides/protect-gateway-http/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-gateway-http.md)): Configure a resource route so Caracal Gateway verifies mandates, brokers provider credentials, forwards the request, and records action-result audit. - [Protect an Express App](https://docs.caracal.run/v1.0/guides/protect-express/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-express.md)): Add the caracalAuth middleware to Express routes to verify mandates and enforce scope requirements. - [Protect a FastAPI App](https://docs.caracal.run/v1.0/guides/protect-fastapi/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-fastapi.md)): Add the CaracalASGIAuth middleware to FastAPI or any ASGI app to verify mandates and enforce scope requirements. - [Protect a FastMCP App](https://docs.caracal.run/v1.0/guides/protect-fastmcp/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-fastmcp.md)): Verify Caracal mandates in a FastMCP server so tool calls are checked before handlers run. - [Protect a Go net/http Service](https://docs.caracal.run/v1.0/guides/protect-nethttp/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-nethttp.md)): Wrap Go HTTP handlers with the nethttp adapter middleware to verify mandates and attach claims to context.Context. - [Protect an MCP Server](https://docs.caracal.run/v1.0/guides/protect-mcp/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/protect-mcp.md)): Gate MCP tool calls with Caracal mandate verification using the framework-neutral verify packages. - [Tail and Query the Audit Stream](https://docs.caracal.run/v1.0/guides/audit-stream/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/audit-stream.md)): Filter audit events, inspect diagnostics, and explain a specific request ID. - [Implement Multi-Agent Delegation](https://docs.caracal.run/v1.0/guides/delegation/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/delegation.md)): Start child Sessions, attach typed constraints, inspect graph impact, and revoke safely. - [Approval Notifications](https://docs.caracal.run/v1.0/guides/approval-notifications/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/approval-notifications.md)): Push approval lifecycle events to your own systems with signed, retried webhook sinks, and verify each delivery before acting on it. - [Production Integration Patterns](https://docs.caracal.run/v1.0/guides/production-patterns/) ([Markdown](https://docs.caracal.run/markdown/v1.0/guides/production-patterns.md)): Choose and validate production enforcement, identity, propagation, and audit boundaries. ## Core Concepts - [Understand the Model](https://docs.caracal.run/v1.0/concepts/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts.md)): Learn the mental model behind scoped authority, policy decisions, delegation, revocation, and audit in Caracal. - [Caracal Mental Model](https://docs.caracal.run/v1.0/concepts/model-overview/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/model-overview.md)): Eight nouns, three verbs, and one decision point that explain Caracal. - [Authority and Enforcement](https://docs.caracal.run/v1.0/concepts/authority-model/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/authority-model.md)): How Caracal enforces authority before a request reaches its target. - [Zones](https://docs.caracal.run/v1.0/concepts/zone/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/zone.md)): The tenancy boundary that owns policies, keys, resources, sessions, and audit. - [Identities and Applications](https://docs.caracal.run/v1.0/concepts/principal/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/principal.md)): Applications, Subjects, Federated users, Authority records, and governed Sessions. - [Resources and Grants](https://docs.caracal.run/v1.0/concepts/resource-grant/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/resource-grant.md)): Resources define protected targets; grant data maps Application roles to Resource scopes. - [Providers](https://docs.caracal.run/v1.0/concepts/provider/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/provider.md)): A provider defines the credential Caracal attaches to an upstream target after access is approved. - [Policies and Policy Sets](https://docs.caracal.run/v1.0/concepts/policy/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/policy.md)): Versioned policy data documents the platform decision contract evaluates inside the STS at token-exchange time. - [Mandates](https://docs.caracal.run/v1.0/concepts/mandate/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/mandate.md)): The short-lived, signed JWT that carries approved session or resource authority. - [Session Delegation](https://docs.caracal.run/v1.0/concepts/delegation/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/delegation.md)): Bounded, cycle-checked authority passed between governed Sessions. - [Delegation Constraints](https://docs.caracal.run/v1.0/concepts/constraint/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/constraint.md)): Resource, scope, lifetime, and hop limits plus audit metadata carried by a Delegation. - [Sessions and Revocation](https://docs.caracal.run/v1.0/concepts/sessions-revocation/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/sessions-revocation.md)): Authority records, Sessions, Delegations, cascading revocation, and the revocation event stream. - [Audit and Request Traces](https://docs.caracal.run/v1.0/concepts/audit-ledger/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/audit-ledger.md)): Decision events and diagnostics that explain Caracal authority. - [Caracal Operator](https://docs.caracal.run/v1.0/concepts/operator/) ([Markdown](https://docs.caracal.run/markdown/v1.0/concepts/operator.md)): The governed natural-language assistant that turns intent into reviewed, audited control-plane changes. ## Operations - [Operate Caracal](https://docs.caracal.run/v1.0/operations/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations.md)): Verified runbooks for deploying, observing, recovering, and changing the open-source Caracal runtime. - [Choose a Deployment Profile](https://docs.caracal.run/v1.0/operations/deployment-profiles/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/deployment-profiles.md)): Decide between the shipped Compose, Helm, and OpenTofu paths without assuming unsupported availability. - [Deploy with Docker Compose](https://docs.caracal.run/v1.0/operations/docker-compose/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/docker-compose.md)): Start and verify the development or released single-host Caracal stack. - [Deploy with Helm](https://docs.caracal.run/v1.0/operations/kubernetes-helm/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/kubernetes-helm.md)): Render, install, verify, and recover the repository Helm chart on Kubernetes 1.30 or newer. - [Choose a Cloud Profile](https://docs.caracal.run/v1.0/operations/cloud-native-profiles/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/cloud-native-profiles.md)): Map operator-owned cloud services to Caracal's portable Helm interfaces. - [Deploy on Managed Kubernetes](https://docs.caracal.run/v1.0/operations/cloud-reference-deployments/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/cloud-reference-deployments.md)): Adapt the External Secrets and Helm examples without treating them as provider-certified deployments. - [Provision with OpenTofu](https://docs.caracal.run/v1.0/operations/opentofu/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/opentofu.md)): Use the provider-neutral bootstrap and Helm wrapper modules within their implemented boundaries. - [Package an Install Kit](https://docs.caracal.run/v1.0/operations/install-kit/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/install-kit.md)): Package the open-source deployment assets, operator inputs, runbooks, and acceptance evidence. - [Configure Service Environment](https://docs.caracal.run/v1.0/operations/env-vars/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/env-vars.md)): Set runtime configuration with the implemented precedence, mode, port, and file-secret rules. - [Harden Production](https://docs.caracal.run/v1.0/operations/tls-hardening/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/tls-hardening.md)): Apply verified network, TLS, secret, browser, container, and egress controls. - [Rotate Keys and Secrets](https://docs.caracal.run/v1.0/operations/key-management/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/key-management.md)): Rotate key classes without losing encrypted state, audit continuity, or service authentication. - [Operate PostgreSQL](https://docs.caracal.run/v1.0/operations/postgres/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/postgres.md)): Run migrations, verify schema protections, monitor capacity, and recover the durable store. - [Operate Redis Streams](https://docs.caracal.run/v1.0/operations/redis/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/redis.md)): Provision, verify, monitor, and recover Caracal stream and revocation transport. - [Scale Capacity](https://docs.caracal.run/v1.0/operations/scale-capacity/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/scale-capacity.md)): Scale from observed bottlenecks without claiming unmeasured performance or availability. - [Monitor Health and Metrics](https://docs.caracal.run/v1.0/operations/observability/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/observability.md)): Gate traffic and changes on verified liveness, readiness, metrics, and end-to-end evidence. - [Configure Alerts](https://docs.caracal.run/v1.0/operations/alerts/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/alerts.md)): Route the alert rules shipped by the Helm chart to specific operator actions. - [Troubleshoot by Symptom](https://docs.caracal.run/v1.0/operations/troubleshooting/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/troubleshooting.md)): Triage an application-visible failure and route it to authorization, configuration, or infrastructure diagnosis. - [Debug Infrastructure Issues](https://docs.caracal.run/v1.0/operations/debugging/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/debugging.md)): Diagnose an unhealthy deployment from orchestration through storage, streams, services, and safety state. - [Recover from Failures](https://docs.caracal.run/v1.0/operations/failure-modes/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/failure-modes.md)): Recover a diagnosed dependency or safety failure in the required order. - [Run Failure Drills](https://docs.caracal.run/v1.0/operations/failure-drills/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/failure-drills.md)): Rehearse one bounded failure at a time and measure detection and recovery without claiming resilience. - [Back Up and Retain Data](https://docs.caracal.run/v1.0/operations/backup-retention/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/backup-retention.md)): Back up and destructively restore the shipped Compose stack with separate secret custody. - [Respond to Incidents](https://docs.caracal.run/v1.0/operations/incident-response/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/incident-response.md)): Contain, preserve, recover, and close security and reliability incidents. - [Plan a Platform Rollout](https://docs.caracal.run/v1.0/operations/platform-rollout-kit/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/platform-rollout-kit.md)): Gate version, configuration, network, secret, and chart changes on measurable safety checks. - [Deploy Policy Changes](https://docs.caracal.run/v1.0/operations/policy-deployment/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/policy-deployment.md)): Validate, activate, verify, and recover policy changes through product-management surfaces. - [Upgrade Caracal](https://docs.caracal.run/v1.0/operations/upgrade/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/upgrade.md)): Upgrade the packaged runtime or Helm release with forward-only migration and explicit rollback checks. - [Export Audit Evidence](https://docs.caracal.run/v1.0/operations/compliance-audit-integration/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/compliance-audit-integration.md)): Operate and verify audit ingestion and optional S3-compatible export without claiming compliance. - [Hand Off to Platform Teams](https://docs.caracal.run/v1.0/operations/platform-team-handoff/) ([Markdown](https://docs.caracal.run/markdown/v1.0/operations/platform-team-handoff.md)): Accept ownership only after operators can deploy, verify, recover, and escalate the OSS runtime. ## Architecture - [Understand Architecture](https://docs.caracal.run/v1.0/architecture/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture.md)): Choose the Caracal flow that explains an integration decision, trust boundary, or operational failure. - [Map the System](https://docs.caracal.run/v1.0/architecture/system-topology/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/system-topology.md)): Map supported callers to runtime services and identify the dependency behind each visible failure. - [Exchange Tokens](https://docs.caracal.run/v1.0/architecture/token-exchange-flow/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/token-exchange-flow.md)): Trace authentication, policy, approval, issuance, and audit through the STS boundary. - [Coordinate Sessions](https://docs.caracal.run/v1.0/architecture/delegation-flow/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/delegation-flow.md)): Trace governed execution and delegated authority from SDK calls through Coordinator and STS. - [Propagate Events](https://docs.caracal.run/v1.0/architecture/event-streams/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/event-streams.md)): Understand asynchronous propagation, durable outboxes, audit replay, and the lag operators can observe. - [Store State](https://docs.caracal.run/v1.0/architecture/storage-model/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/storage-model.md)): Decide what to back up, what can be replayed, and what must never be treated as an application API. - [Manage Keys](https://docs.caracal.run/v1.0/architecture/crypto-keys/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/crypto-keys.md)): Map each key to the boundary it protects and plan rotation without breaking issuance, verification, or evidence. - [Enforce Boundaries](https://docs.caracal.run/v1.0/architecture/trust-boundaries/) ([Markdown](https://docs.caracal.run/markdown/v1.0/architecture/trust-boundaries.md)): Place callers, credentials, services, and failures on the correct side of Caracal trust boundaries. ## Runtime and Console - [Operate Runtime and the Web Console](https://docs.caracal.run/v1.0/runtime-console/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console.md)): Follow the operator journey from starting Caracal through setup, workload launch, observation, and intervention. - [Choose the Right Surface](https://docs.caracal.run/v1.0/runtime-console/cli-and-console/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/cli-and-console.md)): Route each lifecycle, human-management, automation, and workload task to its supported Caracal surface. - [Start and Check the Stack](https://docs.caracal.run/v1.0/runtime-console/stack/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/stack.md)): Start local Caracal services, distinguish health from readiness, open the packaged console, and reset state deliberately. - [Use the Web Console](https://docs.caracal.run/v1.0/runtime-console/console/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/console.md)): Sign in, finish onboarding, complete guided setup, navigate zone state, and understand system-zone restrictions. - [Control Console Access](https://docs.caracal.run/v1.0/runtime-console/console-access/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/console-access.md)): Admit console users, understand sign-in denial, and distinguish account access from zone authority. - [Configure Workloads](https://docs.caracal.run/v1.0/runtime-console/config-file/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/config-file.md)): Configure Launcher workloads for caracal run and local profiles for SDK-managed credentials. - [Run Workloads](https://docs.caracal.run/v1.0/runtime-console/runtime/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/runtime.md)): Launch a command with one-time credential injection and understand approvals, expiry, signals, and exit behavior. - [Manage Product Objects](https://docs.caracal.run/v1.0/runtime-console/admin/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/admin.md)): Maintain zone configuration in the console and hand repeatable workflows to supported automation surfaces. - [Inspect Diagnostics and Audit](https://docs.caracal.run/v1.0/runtime-console/observability/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/observability.md)): Read dashboard posture, diagnose service readiness, and trace authority and management decisions. - [Manage Runtime Authority](https://docs.caracal.run/v1.0/runtime-console/agents/) ([Markdown](https://docs.caracal.run/markdown/v1.0/runtime-console/agents.md)): Investigate Subjects and Authority records, intervene in Sessions and Delegations, and decide eligible Approvals. ## SDKs - [Choose an SDK or Package](https://docs.caracal.run/v1.0/sdks/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks.md)): Choose the Caracal SDK, verification engine, framework adapter, admin client, or state backend for your integration. - [TypeScript SDK](https://docs.caracal.run/v1.0/sdks/typescript/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/typescript.md)): Public API reference for @caracalai/sdk. - [Python SDK](https://docs.caracal.run/v1.0/sdks/python/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/python.md)): Public API reference for caracalai-sdk. - [Go SDK](https://docs.caracal.run/v1.0/sdks/go/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/go.md)): Public API reference for the Go Caracal SDK. - [Verification Layer Overview](https://docs.caracal.run/v1.0/sdks/verification-layer/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/verification-layer.md)): Choose between framework adapters, the verify engine, identity verification, revocation stores, and state backends. - [Framework Adapters](https://docs.caracal.run/v1.0/sdks/adapters/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/adapters.md)): Framework adapters for Caracal-protected resource servers. - [Express Adapter](https://docs.caracal.run/v1.0/sdks/adapters/express/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/adapters/express.md)): Express 5 middleware for Caracal mandate verification. - [ASGI Adapter](https://docs.caracal.run/v1.0/sdks/adapters/asgi/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/adapters/asgi.md)): Pure ASGI middleware that verifies Caracal mandates for FastAPI, Starlette, and Quart resource servers. - [FastMCP Adapter](https://docs.caracal.run/v1.0/sdks/adapters/fastmcp/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/adapters/fastmcp.md)): FastMCP token verifiers for TypeScript and Python servers. - [Go net/http Adapter](https://docs.caracal.run/v1.0/sdks/adapters/nethttp/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/adapters/nethttp.md)): Go middleware for protecting HTTP handlers with Caracal mandate verification. - [Verify Package](https://docs.caracal.run/v1.0/sdks/verify/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/verify.md)): Framework-neutral verification engine for bearer parsing, mandate verification, and revocation checks. - [Identity Package](https://docs.caracal.run/v1.0/sdks/identity/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/identity.md)): JWT verification packages for mandate claims, scopes, targets, agents, delegation, and hop count. - [Revocation Package](https://docs.caracal.run/v1.0/sdks/revocation/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/revocation.md)): Revocation-store interfaces and in-memory stores for resource servers. - [OAuth Package](https://docs.caracal.run/v1.0/sdks/oauth/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/oauth.md)): RFC 8693 token exchange clients for Caracal STS. - [Admin Package](https://docs.caracal.run/v1.0/sdks/admin/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/admin.md)): Automation clients for the Caracal Admin API and Coordinator management surfaces in TypeScript, Python, and Go. - [Redis Revocation Store](https://docs.caracal.run/v1.0/sdks/backends/redis/) ([Markdown](https://docs.caracal.run/markdown/v1.0/sdks/backends/redis.md)): Shared Redis revocation stores and revocation stream consumers. ## API Reference - [Use API Reference](https://docs.caracal.run/v1.0/api/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api.md)): Current HTTP APIs, Gateway proxy behavior, STS exchange, Coordinator endpoints, and stream topics. - [Use the Admin API](https://docs.caracal.run/v1.0/api/control-plane/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api/control-plane.md)): Admin API endpoints served by the Caracal API service. - [Use Coordinator API](https://docs.caracal.run/v1.0/api/coordinator/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api/coordinator.md)): Session, long-lived Session, invocation, and Delegation protocol endpoints served by Coordinator. - [Use STS Endpoint](https://docs.caracal.run/v1.0/api/sts/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api/sts.md)): OAuth token exchange, JWKS, Approval, and internal policy endpoints served by STS. - [Proxy Through Gateway](https://docs.caracal.run/v1.0/api/gateway/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api/gateway.md)): Protected reverse-proxy behavior, routing headers, denial checks, and upstream forwarding. - [Use Event Topics](https://docs.caracal.run/v1.0/api/event-topics/) ([Markdown](https://docs.caracal.run/markdown/v1.0/api/event-topics.md)): Redis Stream topic names, producers, consumers, and contracts. ## Services - [Understand Services](https://docs.caracal.run/v1.0/services/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services.md)): Identify the service behind a user-visible operation and the dependency to check when that operation fails. - [Manage Product State](https://docs.caracal.run/v1.0/services/api/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/api.md)): Understand when to use the API service and how its storage, outbox, and authentication failures appear to operators. - [Coordinate Session State](https://docs.caracal.run/v1.0/services/coordinator/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/coordinator.md)): Understand supported Coordinator use, lease behavior, durable lifecycle state, and propagation failures. - [Issue Mandates](https://docs.caracal.run/v1.0/services/sts/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/sts.md)): Understand supported STS calls, synchronous authority dependencies, approvals, and fail-closed issuance. - [Protect Upstreams](https://docs.caracal.run/v1.0/services/gateway/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/gateway.md)): Understand the Gateway request boundary, deny-before-upstream behavior, synchronous STS dependency, and protocol limits. - [Ingest Audit Evidence](https://docs.caracal.run/v1.0/services/audit/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/audit.md)): Understand the evidence pipeline, supported read surfaces, delayed delivery, integrity failures, and recovery signals. - [Automate Management](https://docs.caracal.run/v1.0/services/control/) ([Markdown](https://docs.caracal.run/markdown/v1.0/services/control.md)): Decide when to enable the optional Control API and understand its credential, gate, replay, scope, and audit dependencies. ## Security and Adoption - [Secure Caracal](https://docs.caracal.run/v1.0/security/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security.md)): Review, verify, harden, and respond to security risks in the open-source runtime. - [Review the Threat Model](https://docs.caracal.run/v1.0/security/threat-model/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/threat-model.md)): Review the canonical OSS threat model, validate boundaries, and record residual risk. - [Harden Security Posture](https://docs.caracal.run/v1.0/security/hardening/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/hardening.md)): Verify a deployed environment against implemented security boundaries. - [Verify a Release](https://docs.caracal.run/v1.0/security/verify-releases/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/verify-releases.md)): Verify archive checksums and GitHub build provenance before installation. - [Generate an Evidence Pack](https://docs.caracal.run/v1.0/security/evidence-pack/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/evidence-pack.md)): Run the repository evidence script and interpret PASS, FAIL, and SKIPPED honestly. - [Review OSS Adoption Readiness](https://docs.caracal.run/v1.0/security/adoption-review/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/adoption-review.md)): Build an evidence-led decision for adopting the self-hosted open-source Caracal product. - [Report a Vulnerability](https://docs.caracal.run/v1.0/security/disclosure/) ([Markdown](https://docs.caracal.run/markdown/v1.0/security/disclosure.md)): Submit a suspected vulnerability through the private channel appropriate to its scope. ## Examples - [Use Examples](https://docs.caracal.run/v1.0/examples/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples.md)): Choose the right runnable example for learning, automation, validation, or full reference-lab integration. - [Run Echo Upstream](https://docs.caracal.run/v1.0/examples/echo-upstream/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/echo-upstream.md)): Start the local protected target that proves Gateway-brokered requests reach an upstream service. - [Bootstrap Control State](https://docs.caracal.run/v1.0/examples/control-bootstrap/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/control-bootstrap.md)): Keep an agent environment in sync with a declared plan through a scoped Control API automation key. - [Check Provider Readiness](https://docs.caracal.run/v1.0/examples/provider-preflight/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/provider-preflight.md)): Validate service readiness, dependencies, provider configuration, reachability, and policy authorization before the first Gateway request. - [Iterate Policy Safely](https://docs.caracal.run/v1.0/examples/policy-iterate/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/policy-iterate.md)): Diagnose a denied request, simulate a candidate policy-set version, regression-check expected decisions, and activate only when every gate passes. - [Launch Research Agent](https://docs.caracal.run/v1.0/examples/research-agent/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/research-agent.md)): Run a plain CLI agent with Google and OpenAI provider credentials injected by caracal run. - [Run Lynx Capital](https://docs.caracal.run/v1.0/examples/lynx-capital/) ([Markdown](https://docs.caracal.run/markdown/v1.0/examples/lynx-capital.md)): Run the agent-swarm reference protected by one Caracal managed application per permission boundary and per-agent labeled sessions. ## Reference - [Use Reference](https://docs.caracal.run/v1.0/reference/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference.md)): Search exact Caracal terms, configuration, limits, errors, compatibility, release surfaces, and wire contracts. - [FAQ](https://docs.caracal.run/v1.0/reference/faq/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/faq.md)): Stable, searchable answers to recurring Caracal modeling, runtime, provider, troubleshooting, and repository-scope questions. - [Glossary](https://docs.caracal.run/v1.0/reference/glossary/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/glossary.md)): Canonical Caracal terms and names used across the documentation. - [Error Codes](https://docs.caracal.run/v1.0/reference/errors/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/errors.md)): Shared Caracal error codes and response shape. - [Configuration Keys](https://docs.caracal.run/v1.0/reference/configuration/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/configuration.md)): Runtime profile, service environment, and deployment configuration keys. - [Configuration Order](https://docs.caracal.run/v1.0/reference/config-precedence/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/config-precedence.md)): How Caracal chooses runtime profiles, environment values, file secrets, and deployment values. - [Defaults and Limits](https://docs.caracal.run/v1.0/reference/defaults-and-limits/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/defaults-and-limits.md)): Current ports, TTLs, timeouts, limits, and operational defaults. - [CLI Exit Codes](https://docs.caracal.run/v1.0/reference/runtime-exit-codes/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/runtime-exit-codes.md)): Exit behavior for top-level caracal runtime CLI commands and web console launch. - [Compatibility](https://docs.caracal.run/v1.0/reference/compatibility/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/compatibility.md)): Supported runtimes, deployment targets, version combinations, and v0.2 stability rules. - [Release Map](https://docs.caracal.run/v1.0/reference/release-package-runtime-map/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/release-package-runtime-map.md)): Lockstep SemVer mapping for packages, images, binaries, chart, release records, and documentation. - [Wire Contracts](https://docs.caracal.run/v1.0/reference/interoperability-contracts/) ([Markdown](https://docs.caracal.run/markdown/v1.0/reference/interoperability-contracts.md)): JSON schemas and fixtures for Caracal wire contracts. ## Contributing - [Contribute to Caracal](https://docs.caracal.run/v1.0/contributing/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing.md)): Contributor guide for local setup, project standards, workflow, validation, governance, and releases. - [Set Up Locally](https://docs.caracal.run/v1.0/contributing/setup/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/setup.md)): Install dependencies and start a local Caracal development stack. - [Follow Project Standards](https://docs.caracal.run/v1.0/contributing/style/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/style.md)): Repository conventions for code, docs, naming, command ownership, and product boundaries. - [Make a Change](https://docs.caracal.run/v1.0/contributing/workflow/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/workflow.md)): How to plan, implement, validate, and submit Caracal changes. - [Validate Changes](https://docs.caracal.run/v1.0/contributing/testing/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/testing.md)): Test commands and validation strategy for Caracal contributors. - [Understand Governance](https://docs.caracal.run/v1.0/contributing/governance/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/governance.md)): Maintainer ownership, contribution process, security process, and community expectations. - [Release Caracal](https://docs.caracal.run/v1.0/contributing/release/) ([Markdown](https://docs.caracal.run/markdown/v1.0/contributing/release.md)): Lockstep SemVer releases, package publishing, protected workflows, and rollback rules.