Security-first authority and delegation system for AI agents

---

Overview

Caracal is an authority plane for operating AI agents safely in real environments. It solves a concrete platform problem: agents need access to tools, APIs, and providers, but platform teams need that access to be scoped, short-lived, revocable, and auditable without placing provider secrets inside agent code.

Read the full documentation at docs.caracal.run.

---

Community

GitHub's Open Source Friday	LFX Mentorship 2026	Microsoft for Startups

---

Installation & Setup

End Users

Prerequisites

• Docker Desktop 4.x or Docker Engine 24+ with Compose v2
• Git 2.x
• GitHub CLI gh for installer provenance verification

Install

The installer provides the thin caracal runtime CLI and the caracal-console management interface.

Version examples below pin v2026.06.10-rc.1. Check GitHub Releases for the latest available tag. Unpinned installs follow GitHub's latest stable release. Pin a version: --version vYYYY.MM.DD on Unix or -Version vYYYY.MM.DD in PowerShell.
Change install directory: --install-dir /path on Unix or -InstallDir C:\path in PowerShell. Unix installers also honor PREFIX/CARACAL_PREFIX and DESTDIR for staged installs. Uninstall: rerun the installer with --uninstall on Unix or -Uninstall in PowerShell. Provenance verification is required by default.

Linux (amd64 / arm64)

# Console
curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.sh | \
  sh -s -- --version v2026.06.10-rc.1

Installs to ~/.local/bin and verifies release provenance by default. Override with --install-dir /usr/local/bin (may need sudo) or use packaging-style roots such as PREFIX=/usr DESTDIR=/tmp/pkg.

macOS (Intel / Apple Silicon)

# Console
curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.sh | \
  sh -s -- --version v2026.06.10-rc.1

If Gatekeeper blocks the binary: xattr -d com.apple.quarantine ~/.local/bin/caracal.

Windows (amd64) PowerShell

# Console
$installer = "$env:TEMP\install-console.ps1"
iwr -useb https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.ps1 -OutFile $installer
powershell -ExecutionPolicy Bypass -File $installer -Version v2026.06.10-rc.1

Installs to %LOCALAPPDATA%\Programs\caracal and verifies release provenance by default. Remove installed binaries and the user Path entry with -Uninstall. Requires Docker Desktop with WSL2.

Start the stack

caracal up                            # start all services, override with `CARACAL_VERSION=vYYYY.MM.DD caracal up`
caracal status [--ready]              # probe all services
caracal down                          # stop; add -v to remove volumes
caracal purge                         # interactive cleanup (containers, volumes, config, runtime, examples, caches)
caracal console                       # launch Console
caracal run -- node worker.js         # workload execution

Contributors

Prerequisites

• Node.js 24+
• pnpm 11.1.1
• Docker Engine 24+ with Compose v2 (or Docker Desktop 4.x)
• Git 2.x
• Go 1.26+ (only when changing Go services or shared Go packages)
• Python 3.14+ (only when changing Python packages)
• Bun (only when building distributable runtime/console binaries)

Run pnpm install after cloning for the standard Node workspace setup. Run pnpm run setup when you need the full cross-platform developer environment with Go modules, Python test/style tooling, and editable Python packages.

See CONTRIBUTING.md for clone, setup, testing, and pull request workflow.

---

Maintainers

RAWx18

Slo-Pix

---

Contributing

See CONTRIBUTING.md for setup, workflow, tests, and pull request standards.

---

License

Caracal is open-source software licensed under the Apache-2.0 License. See the LICENSE file for details.

Developed by Garudex Labs.