H
Caracal
README

Caracal gives AI agents authority, not credentials: short-lived, scoped, instantly revocable access to tools, APIs, and MCP servers. Every action is approved by policy before it runs.

caracal up
Features
01
Agents never hold API keys.

Real credentials are attached server-side after approval and expire in minutes. Agent code, prompts, and logs have nothing to steal.

OPENAI_API_KEY••••
expires in0:30
02
Every agent run gets its own identity.

Unlimited agents under one credential, each individually attributed, policed, and revocable. No shared service accounts, no credential sprawl.

anton1 credential
↳ agent-7f3a [triage]
↳ agent-2c1b [refunds]
03
Approve actions before they run.

Every request is checked against your policy up front, down to the exact endpoint, and rules change without redeploying a single agent.

payments:readpolicy →allow
tickets:writepolicy →deny
customer:exportpolicy →approval
04
Stolen tokens are useless.

Access tokens live minutes and work exactly once. A leaked or replayed token is rejected at the gate and flagged in audit.

token · ttl 15mused once ✓
same token againreplay rejected
05
Delegation that can only narrow.

Agents can hand work to sub-agents, never with more access than they hold. Every hop is re-verified on every call.

parent [read, write]child [read]
06
One revocation kills the chain.

Cut off a runaway agent and everything it delegated loses access at once, even responses already streaming stop mid-flight.

revokedagent-7f3a
↳ 3 child agents cut off
07
Human sign-off for risky actions.

Sensitive actions pause for approval. Each decision unlocks exactly one request and can never be reused for anything else.

challengeproofgranted
08
Audit evidence, not just logs.

Every allow, deny, and approval lands in an append-only, tamper-evident trail you can export and hand to auditors.

10:50agent-7f3aallowpayments:read
10:48agent-2c1bdenytickets:write
10:45agent-9d4eapprovalcustomer:read
09
Guard your APIs and MCP tools.

Put a verification gate in front of any API or MCP server, or verify in-process with drop-in framework adapters.

MCPRESTFastAPIExpress+6
Trust Layer

One SDK to give agents short-lived, gateway-routed authority in TypeScript, Python, or Go.

ts agent.ts
$ npm install @caracalai/sdk
import { Caracal } from "@caracalai/sdk"

// Loads your profile or environment config.
// No provider keys anywhere in your code.
const caracal = new Caracal()
Works With
Languages
  • TypeScript
  • Python
  • Go
  • Any CLI via caracal run
+ More native SDKs on the way
AI Frameworks
  • LangChain
  • LangGraph
  • CrewAI
  • OpenAI Agents SDK
  • Custom agents
+ Any framework (Caracal is framework-agnostic)
Provider Types
  • API key
  • OAuth 2.0 user (authorization code)
  • OAuth 2.0 machine (client credentials)
  • Bearer token
  • Caracal mandate
+ None · MCP · Provider SDK
Infrastructure

Caracal is a small set of self-hosted services, each owning one bounded part of the authority lifecycle. Backed by Postgres and Redis, deployed with Docker Compose or Helm.

STS

decides

The decision point for all authority.

  • +Policy-checked token exchange
  • +Short-lived signed mandates
  • +Human approval holds
  • +End-user identity federation

Gateway

enforces

Fronts your APIs and verifies every request.

  • +Per-request mandate verification
  • +Replay and revocation checks
  • +Injects upstream credentials
  • +Safe, audited egress

Coordinator

tracks

Owns the live authority graph.

  • +Agent sessions and leases
  • +Delegation graph
  • +Cascading termination
  • +Lifecycle events

Audit

proves

Turns every decision into evidence.

  • +Signed event ingestion
  • +Tamper-evident hash chain
  • +Retention and export
  • +Query and search

Admin API

manages

The programmable control plane.

  • +Zones, applications, resources
  • +Providers and their secrets
  • +Policies and grants
  • +Automation via Admin SDK

Console

operates

The operator surface for the platform.

  • +Manage the whole platform
  • +Inspect sessions and delegations
  • +Decide pending approvals
  • +Explain any request
Contributors

Built by a community of 20+ contributors.

RAWx18yashgo0018pratyush07-hubMohammad-Ali-HaiderSlo-Pixumar-aziz-devaayushprsinghAshutoshx7

Authority Before Autonomy

© Garudex Labs 2026 | Caracal, a product of Garudex Labs