Install Caracal

Running Caracal locally takes two pieces:

• The caracal CLI - a single executable that starts and stops the local stack and launches your programs under Caracal’s control.
• Docker - the local stack runs as containers: Caracal’s services, a PostgreSQL database, a Redis cache, and the web console, the browser interface where you will create and manage everything in the next page.

You install one binary; Docker provides the rest. No source checkout, package build, or separate database install is required.

Prerequisites

• a supported Linux, macOS, or Windows machine;
• Docker 25 or later with Compose v2;
• curl or a browser for downloading a release;
• permission to install one executable on your PATH.

Install the CLI

The install script downloads the archive for your platform, verifies its checksum, and places caracal on your PATH. The commands below pin this release; drop --version (or set CARACAL_VERSION) to track the latest stable release instead.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install.sh | sh -s -- --version v1.0.0

Windows

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

The installer places caracal.exe in %LOCALAPPDATA%\Programs\caracal and adds it to the user Path; open a new shell afterward.

Prefer to download and verify manually? Each release ships platform archives (caracal-runtime-*), a manifest.json, and a SHA256SUMS file. Pick the archive matching your platform (linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, or windows-amd64):

Linux / macOS

tag=v1.0.0
platform=linux-amd64   # or linux-arm64, darwin-amd64, darwin-arm64
curl -fsSLO "https://github.com/Garudex-Labs/caracal/releases/download/${tag}/caracal-runtime-${platform}-${tag}.tar.gz"
curl -fsSLO "https://github.com/Garudex-Labs/caracal/releases/download/${tag}/SHA256SUMS"
sha256sum --ignore-missing --check SHA256SUMS   # macOS: shasum -a 256 --ignore-missing --check SHA256SUMS
tar -xzf "caracal-runtime-${platform}-${tag}.tar.gz"
install -m 0755 caracal ~/.local/bin/caracal

Make sure the destination directory is on your PATH.

Windows

$tag = 'v1.0.0'
Invoke-WebRequest "https://github.com/Garudex-Labs/caracal/releases/download/$tag/caracal-runtime-windows-amd64-$tag.zip" -OutFile caracal.zip
Invoke-WebRequest "https://github.com/Garudex-Labs/caracal/releases/download/$tag/SHA256SUMS" -OutFile SHA256SUMS
Get-FileHash .\caracal.zip -Algorithm SHA256   # compare with the matching SHA256SUMS entry
Expand-Archive .\caracal.zip -DestinationPath $env:LOCALAPPDATA\Programs\caracal

Add %LOCALAPPDATA%\Programs\caracal to the user Path and open a new shell.

Both install scripts always verify checksums. With the GitHub CLI gh installed they also verify build provenance; set CARACAL_REQUIRE_PROVENANCE=1 to make a missing provenance check fail the install instead of skipping it. For deeper supply-chain checks, signatures, and container image verification, see Verify a Release.

Verify the Installation

The same command works in every shell:

caracal --version

It should print the installed version without errors.

Verify Docker

docker compose version

If this fails, install or start Docker Desktop (macOS, Windows) or Docker Engine with the Compose plugin (Linux) before continuing.

Start the Local Stack

caracal up
caracal status --ready

caracal up pulls and starts the containers; caracal status --ready waits until every service reports healthy. When readiness succeeds, the web console is being served at http://localhost:3001.

Enable Console Sign-In

The console ships locked down: nobody can register until you, from the machine that runs the stack, allow their email. Allow yours:

caracal allowlist add <your email>

The change applies immediately; no restart is needed. The same command family later manages suspension, restoration, and removal - see Control Console Access for the full lifecycle.

An allowlisted email still needs a way to sign in. Pick one and add its settings to the operator env file the stack reads - $CARACAL_HOME/caracal.env, whose exact per-platform path and editor command are in Configure Service Environment - then rerun caracal up:

Sign-in method	Required variables
Google or GitHub	GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET or GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET. OAuth callback URL: http://localhost:3001/api/auth/callback/google or .../github.
Email and password	CARACAL_PASSWORD_SIGNUP=true, plus CARACAL_SMTP_URL and CARACAL_SMTP_FROM so the required verification email can be delivered; the console fails closed without a mail transport.

For OAuth, create an OAuth app in the Google Cloud console or GitHub developer settings, set its callback URL to the value above, and paste the client ID and secret into caracal.env. With email/password sign-up, registration sends a verification link over SMTP and the account signs in after the link is confirmed. The full sign-in reference lives in Configure Service Environment.

Why is sign-in this strict on a local machine?

The packaged runtime runs the console in published mode, which enforces the same fail-closed sign-in posture you would run in production: host-controlled admission plus a verified sign-in method. This is a one-time setup; everything after it happens in the browser.

Do not sign in yet - the next page walks through onboarding and your first protected setup in one continuous flow.

Common Mistakes

• If the shell cannot find caracal after installation, reopen the shell or add the install directory to PATH.
• Do not use caracal purge to recover from a normal startup error; it intentionally removes all local state.
• If you have a Caracal source checkout for contribution work, keep it separate: this path uses the released caracal executable, not the source-tree pnpm caracal command.

Expected Outcome

caracal status --ready exits successfully, http://localhost:3001 responds, your email is allowlisted, and one sign-in method is configured. The console’s sign-in and registration pages live at /sign-in and /sign-up under that origin. Readiness proves the local services are up; nothing is protected yet - that is the next page.

Platform Notes

Platform	Architectures	Notes
Linux	amd64, arm64	Requires curl or wget, tar, and sha256sum or shasum.
macOS	amd64, arm64	If Gatekeeper quarantines the binary, remove quarantine from the installed file.
Windows	amd64	Open a new shell after the installer updates the user Path.

Next Step

Continue with First Protected Call.