caracal-core 0.6.0

Pre-execution authority enforcement system for AI agents

Pre-execution authority enforcement for AI agents

---

Overview

Caracal is a pre-execution authority enforcement system for AI agents and automated software operating in production environments. It exists at the exact boundary where decisions turn into irreversible actions—API calls, database writes, deployments, or workflow triggers.

Instead of relying on broad roles or static API keys, Caracal enforces the principle of explicit authority: no action executes unless there is a cryptographically verified, time-bound mandate issued under a governing policy.

---

Quickstart

Caracal offers two distinct interfaces for managing authority.

1. Caracal Flow (TUI)

Target: Security Teams, Governance Officers, and Developers.

Caracal Flow is an interactive terminal interface for onboarding, monitoring authority ledgers, and managing infrastructure. It includes an Onboarding Wizard to help you configure your first principal, policy, and mandate in minutes.

╔═══════════════════════════════════════════════════════════════════╗
║                                                                   ║
║     ██████╗ █████╗ ██████╗  █████╗  ██████╗ █████╗ ██╗            ║
║    ██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗██║            ║
║    ██║     ███████║██████╔╝███████║██║     ███████║██║            ║
║    ██║     ██╔══██║██╔══██╗██╔══██║██║     ██╔══██║██║            ║
║    ╚██████╗██║  ██║██║  ██║██║  ██║╚██████╗██║  ██║███████╗       ║
║     ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝       ║
║                                                                   ║
║                   C A R A C A L  F L O W                          ║
║         Pre-Execution Authority Enforcement System                ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

Launch Caracal Flow:

caracal-flow

Capabilities in Flow:

• Onboarding Wizard: Guided setup for principals and policies.
• Authority Ledger: Real-time stream of authorization decisions.
• Principal Hub: Manage identities and cryptographic key pairs.
• Infrastructure Setup: Provision PostgreSQL and Kafka with one click.

---

2. Caracal Core (CLI & SDK)

Target: Developers and System Architects.

Caracal Core provides the high-performance CLI and SDK for deep integration into agentic loops and CI/CD pipelines.

Installation:

pip install caracal-core

Example CLI Commands:

# Register a principal (agent identity)
caracal principals register --name "web-scraper-01" --type agent

# Create an authority policy allowing search on specific resources
caracal policies create --principal-id <ID> --resources "google.com/*" --actions "GET,POST"

# Issue a time-bound execution mandate
caracal mandates issue --principal-id <ID> --ttl 1800

# Query the authority ledger
caracal authority-ledger query --principal-id <ID>

---

Core Concepts

Principals Identities (agents, users, or services) that can hold and exercise authority. Principals use ECDSA P-256 keys for cryptographic attestation.

Authority Policies Governing rules that define the maximum validity, allowed resource patterns, and permitted actions for a given principal.

Execution Mandates Short-lived, cryptographically signed tokens that grant specific rights. Mandates are checked by the Caracal Gateway before any action is executed.

Authority Ledger A high-performance, immutable audit trail of every authorization request, decision, and enforcement event.

---

Infrastructure

Caracal scales from local development to enterprise-grade throughput.

Environment	Database	Messaging	Event Bus	Use Case
Standard	SQLite	File-based	In-Memory	Local development, testing, and TUI default.
Enterprise	PostgreSQL	Kafka	Redis/Redpanda	High-availability production enforcement.

---

Project Structure

• caracal/core/: Core engine for policy evaluation and mandate issuance.
• caracal/flow/: TUI layer for interactive management.
• caracal/db/: Persistence layer supporting multiple backends.
• k8s/: Kubernetes manifests for production deployment.
• deploy/: Infrastructure automation scripts.

---

License

Caracal is open-source software licensed under the AGPL-3.0. See the LICENSE file for details.

Developed by Garudex Labs.