Skip to main content

Open Source Developers

This lane explains how the open-source repository is organized and how its main subsystems fit together.

Audience: Developer

Context: Use this section when you are reading, debugging, extending, or contributing to the Caracal codebase.

Core Explanation​

The repository is organized around a container-first runtime plus a Python package that contains:

  • runtime entrypoints and orchestration helpers
  • a Click-based in-container CLI
  • a Flow terminal UI
  • core authority, delegation, ledger, and cryptography modules
  • PostgreSQL, Redis, Merkle, monitoring, and migration layers
  • provider registry and integration helpers
  • deployment, sync, and release utilities

The developer docs are split so that architecture and module boundaries come before workflow and maintenance topics.

Reading Order​

After that, move to:

Internal Behavior​

Two repository rules explain much of the structure:

  • the host caracal command is orchestration-only
  • the product workflows live inside the runtime container, but they are still implemented in this same Python package

That is why the repository mixes deployment artifacts, runtime entrypoints, CLI code, TUI code, and core modules under one tree.

Edge Cases And Constraints​

  • Some modules still carry legacy compatibility surfaces, but the supported runtime model is now PostgreSQL plus Redis plus Merkle, not a pluggable local-file backend.
  • Enterprise-related modules and env vars appear in public code because the open-source runtime exposes public connector surfaces, but enterprise internals remain out of scope here.
AI tools
On this page