Install Caracal

Install the released tools when you want to run Caracal as a product. The caracal CLI owns local runtime lifecycle and workload execution. The Console owns product management: zones, applications, resources, providers, policies, sessions, audit, diagnostics, and Control workflows.

Install CLI and Console

The installer downloads release archives from GitHub, verifies each archive against SHA256SUMS, verifies GitHub provenance attestations with gh, and installs:

• caracal: local runtime CLI for up, down, status, purge, run, and console.
• caracal-console: interactive Console for product-management workflows.

To verify a download yourself, or to verify archives and container images fetched directly instead of through the installer, follow Verify a Release.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.sh | sh

Pin a release:

curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.sh | \
  sh -s -- --version vYYYY.MM.DD

By default the installer writes to ~/.local/bin and requires provenance verification. Override the install path with --install-dir /path/to/bin or CARACAL_INSTALL_DIR=/path/to/bin. Packaging flows can use --prefix, CARACAL_PREFIX, PREFIX, and DESTDIR; for example, PREFIX=/usr DESTDIR=/tmp/caracal-package sh install-console.sh stages files under /tmp/caracal-package/usr/bin. Use --no-verify-provenance only when you explicitly need to skip provenance verification.

Uninstall the Unix binaries from the same install directory:

install-console.sh --install-dir ~/.local/bin --uninstall

Windows

$installer = "$env:TEMP\install-console.ps1"
iwr -UseBasicParsing https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-console.ps1 -OutFile $installer
powershell -ExecutionPolicy Bypass -File $installer

Pin a release:

powershell -ExecutionPolicy Bypass -File $installer -Version vYYYY.MM.DD

The Windows installer writes to %LOCALAPPDATA%\Programs\caracal by default, requires provenance verification, and adds the install directory to the user Path. Open a new shell after installation. Use -NoVerifyProvenance only when you explicitly need to skip provenance verification.

Uninstall the Windows binaries:

powershell -ExecutionPolicy Bypass -File $installer -Uninstall

The Windows uninstall path also removes the installer-managed user Path entry.

Verify Installation

caracal --version
caracal-console --version
caracal status --help

On Windows PowerShell:

caracal --version
caracal-console --version
caracal status --help

Use caracal for local lifecycle and workload execution only. Use caracal console or caracal-console for product management.

Verify Docker

Running the open-source stack locally requires Docker 24+ with the Compose v2 plugin:

docker compose version

On Windows PowerShell:

docker compose version

The local stack includes PostgreSQL and Redis containers. You do not need to install those databases separately for Get Started.

Platform Notes

Platform	Architectures	Notes
Linux	amd64, arm64	Requires curl or wget, tar, sha256sum or shasum, and GitHub CLI gh for provenance verification.
macOS	amd64, arm64	Requires GitHub CLI gh; if Gatekeeper quarantines the binary, remove quarantine from the installed file.
Windows	amd64	Requires GitHub CLI gh; use the PowerShell installer and open a new shell after installation.

Next Step

Continue with First Protected Call.