Open Source End Users
This lane explains how to install, operate, configure, and troubleshoot the open-source runtime.
Audience: User
Context: Use this section if you are running Caracal rather than modifying its implementation.
Core Explanation
End-user documentation is organized around the real runtime lifecycle:
- install the command and confirm Docker support
- start the runtime stack from the host
- enter either the in-container CLI or Flow
- create or select a workspace
- configure providers, principals, policies, and mandates
- monitor, back up, and troubleshoot the system
The user-facing docs are intentionally separate from contributor internals. They explain operational behavior, not repository implementation details.
What This Lane Covers
- runtime installation and prerequisites
- the host command surface
- the in-container CLI and Flow
- workspace configuration and secrets handling
- provider registration and provider-scoped scopes
- authority lifecycle workflows
- backups, restore, and troubleshooting
- public security behavior and reporting paths
Suggested Reading Order
Internal Behavior
Even as an operator, it helps to understand two boundary rules:
- host
caracalcommands control containers and runtime lifecycle - the actual product workflows happen inside the runtime through the in-container CLI, Flow, and the
mcpservice
That distinction explains why some commands work before the stack is running and others do not.
Edge Cases And Constraints
- A workspace is not just a label. It is a real directory under
CARACAL_HOME/workspaces/<name>that owns its ownconfig.yaml, logs, backups, cache, keys, and Flow state. - Policy and mandate scopes are validated against provider definitions stored in the current workspace. In practice, provider setup usually comes before policy and mandate issuance.
- Some commands surface enterprise-related options or sync behavior. Those are public connector surfaces, not enterprise implementation details.