README.md

July 19, 2026 · View on GitHub

Authority, not credentials: Policy-checked, attributable, revocable, provable AI agent authorization.

Supported By:

Why Caracal

"Gateway-mediated agents never hold upstream credentials. Every action is policy-approved before it runs, scoped to exactly what was delegated, revocable in one call, and recorded as tamper-evident evidence."

AI agents are entering production with long-lived API keys in their environment, broader access than any task needs, and no answer to "which agent did this, under whose authority?"

One prompt injection, leaked key, or runaway loop turns an assistant into an incident. Security reviews block launches. Auditors have nothing to inspect.

Existing tools weren't built for this: identity providers register agents but never see their actions, secrets managers hand the credential to the workload, and API gateways route traffic without deciding anything. Caracal is the missing control plane. It decides what an agent may do before every action, proves what it actually did, and shuts it down instantly when something goes wrong.

How It Works

For gateway-mediated calls, agents never receive upstream credentials. They carry mandates: short-lived, signed grants of authority that can only shrink as work is delegated. Caracal's gateway injects the real credential at call time, so the upstream credential never enters the agent process.

flowchart LR
  A[Agent] -- requests authority --> STS[Policy decision<br/>default deny]
  STS -- short-lived mandate --> A
  A -- presents mandate --> GW[Caracal Gateway]
  GW -- real credential injected --> API[Tool / API / MCP server]
  STS -. every decision .-> AUDIT[(Tamper-evident audit)]
  GW -. every call .-> AUDIT

Capability	Outcome for your team
No standing secrets	For gateway-mediated calls, upstream credentials stay at the edge and are injected only for the request.
Delegation that only narrows	Agents hand work to sub-agents, never with more access than they hold. Least privilege is enforced, not requested.
Decisions before actions	Default-deny policy evaluates every request before it reaches a resource, not flagged in a log afterwards.
One-call kill switch	Revoke an agent and everything it started loses access at once. No waiting for tokens to expire.
Human approval for risky actions	Approval gates hold high-risk operations for an authenticated approver before they execute.
Evidence, not just logs	An append-only, tamper-evident trail of every decision, exportable for SOC 2, EU AI Act, NIST AI RMF, and OWASP Agentic reviews.

Why Not Something Else?

Alternative	What's missing
Identity providers	Register agents; never see their actions. No per-call decisions, no delegation limits, no evidence.
Secrets managers	Hand the credential to the workload. A compromised agent is a leaked secret.
API gateways	Route and rate-limit; carry no authority model and no delegation semantics.
Building it yourself	A proxy + vault + policy engine gets you plumbing, not narrowing delegation, revocation propagation, or a tamper-evident audit chain. Then you maintain it forever.

Caracal is standards-native: OAuth 2.0 token exchange (RFC 8693), OPA policy, and MCP integrations. It fits the stack you already run instead of replacing it.

Works With Your Stack

TypeScript, Python, and Go SDKs. Drop-in verification for MCP servers, Express, FastAPI/ASGI, and Go net/http. Runs anywhere Docker runs: your infrastructure, your data.

Read the full documentation at docs.caracal.run.

Get Started

Prerequisites

Docker Desktop 4.27+ or Docker Engine 25+ with Compose v2
Git 2.x

Install Released Version

Check GitHub Releases for the latest available tag.

Pin a version: --version vX.Y.Z on Unix or -Version vX.Y.Z in PowerShell.

Linux (amd64 / arm64)

curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install.sh | \
  sh -s -- --version v0.2.1

macOS (Intel / Apple Silicon)

curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install.sh | \
  sh -s -- --version v0.2.1

Windows (amd64) PowerShell

$installer = "$env:TEMP\install.ps1"
iwr -useb https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install.ps1 -OutFile $installer
powershell -ExecutionPolicy Bypass -File $installer -Version v0.2.1

Start the stack

caracal up                            # start all services, override with `CARACAL_VERSION=vX.Y.Z caracal up`
caracal status [--ready]              # probe all services

caracal down                          # stop; add -v to remove volumes
caracal purge                         # interactive cleanup (containers, volumes, config, runtime, caches)

Before your first sign-in, enable Google/GitHub OAuth or email/password (with SMTP) in $CARACAL_HOME/caracal.env, then allowlist your email. See Enable Console Sign-In. Once the stack is up, the console is served at http://localhost:3001.

caracal allowlist add you@example.com # admit your first console user, Port:3001 (Console UI)

caracal run -- node worker.js         # workload execution

Contributing

See CONTRIBUTING.md for setup, workflow, tests, and pull request standards.

Editions


Community Edition	Apache-2.0. The complete authority model (mandates, delegation, policy, revocation, audit), self-hosted, with no feature gates on security.
Enterprise Edition	Caracal run for you: managed multi-tenancy, hosted control plane, SSO/SCIM, and a fully managed data plane. Compare editions or book a call.

Maintainers

RAWx18

Slo-Pix

Security & Trust

Caracal is built to be the enforcement point you can audit, not another black box: a published threat model, signed releases with verified assets, OpenSSF Best Practices and Scorecard tracking, and a tamper-evident audit chain at runtime. Start with the Enterprise Security Readiness review checklist.

Report vulnerabilities privately through SECURITY.md.

License

Caracal is open-source software licensed under the Apache-2.0 License. See the LICENSE file for details.

Developed by Garudex Labs.