Skip to content

Map the System

Caracal has six primary HTTP services plus Postgres and Redis.

Topology

flowchart TB
  subgraph Clients
    Console[Console]
    SDK[SDKs and caracal run]
    ResourceClient[Protected-resource clients]
    Automation[Control/Admin automation]
  end

  subgraph Caracal
    API[API :3000]
    STS[STS :8080]
    Gateway[Gateway :8081]
    Audit[Audit :9090]
    Coordinator[Coordinator :4000]
    Control[Control plugin in API, optional]
  end

  Postgres[(Postgres)]
  Redis[(Redis Streams)]
  Upstream[Protected upstreams]

  Console --> API
  Console --> Coordinator
  SDK --> STS
  ResourceClient --> Gateway
  Automation --> Control
  Control --> API
  Gateway --> Upstream
  API --> Postgres
  STS --> Postgres
  Gateway --> Postgres
  Audit --> Postgres
  Coordinator --> Postgres
  API --> Redis
  STS --> Redis
  Gateway --> Redis
  Audit --> Redis
  Coordinator --> Redis

Service Responsibilities

Service	Responsibility
API	Zones, applications, providers, resources, policies, policy sets, grants, step-up challenges, admin audit, and API outbox.
STS	OAuth token exchange, mandate issuance, policy evaluation, JWKS, step-up status, policy simulation, signing-key rotation internals.
Gateway	Protected reverse proxy, inbound mandate verification, per-request STS exchange, SSRF guard, revocation checks, audit replay.
Audit	Redis audit ingestion, DLQ, tamper checks, retention, search, metrics.
Coordinator	Agent sessions, agent services, delegations, invocations, sweeper jobs, Coordinator outbox.
Control	Optional remote management invoke endpoint gated by token auth, replay protection, rate limiting, and runtime gate file.

Deployment Shapes

Shape	Source
Local development	`infra/docker/docker-compose.yml` through `caracal up`.
Self-hosted Compose	`infra/docker/runtime-compose.yml`.
Kubernetes	`infra/helm/caracal`.

Next Step

Use Exchange Tokens to follow how workloads receive scoped mandates.