Understand Architecture

Caracal is a pre-execution authority system for AI agents. It separates control-plane management, token exchange, protected-resource routing, audit evidence, and agent/delegation coordination into independent services backed by Postgres and Redis Streams.

System Overview

flowchart LR
  Console[Console/Admin SDK] --> API[Control-Plane API]
  Workload[SDK or caracal run] --> STS[STS]
  Client[Protected request] --> Gateway[Gateway]
  Agent[Agent SDK] --> Coordinator[Coordinator]
  API --> Postgres[(Postgres)]
  STS --> Postgres
  Gateway --> Postgres
  Coordinator --> Postgres
  API --> Redis[(Redis Streams)]
  STS --> Redis
  Gateway --> Redis
  Coordinator --> Redis
  Redis --> Audit[Audit]
  Audit --> Postgres
  Control[Control API] --> API

Core Design Choices

Choice	Effect
Postgres as source of truth	Product state, policy versions, grants, sessions, audit rows, agents, delegations, and outboxes are durable.
Redis Streams for propagation	Audit, invalidation, revocation, key, agent, invocation, and delegation events move asynchronously.
STS for mandate issuance	Every protected access path receives a scoped, short-lived mandate.
Gateway for protected upstreams	Gateway verifies inbound authority, exchanges with STS, blocks unsafe routing, and emits audit evidence.
Coordinator for agent authority	Agent sessions, service leases, delegation edges, and invocation lifecycle stay explicit.
Console/API boundary	Human management uses Console; automation uses Control/Admin APIs; runtime CLI remains lifecycle-only.

System Flows

Need	Page
Identify services, clients, and dependencies	Map the System
Understand STS mandate issuance	Exchange Tokens
Understand agent sessions and delegation	Coordinate Agents

State and Safety

Need	Page
Understand Redis Streams and outboxes	Propagate Events
Understand durable data ownership	Store State
Understand signing, HMACs, JWKS, and rotation	Manage Keys
Understand security and command boundaries	Enforce Boundaries

Next Step

Start with Map the System before tracing request and state flows.

For service-by-service detail, continue to Understand Services. For deployment detail, use Operations.