---
title: "Install Caracal"
url: "https://docs.caracal.run/v1.0/get-started/install-caracal/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/get-started/install-caracal.md"
description: "Install the caracal CLI, verify Docker, and start the local stack that the rest of Get Started uses."
page_type: "workflow"
concepts: []
requires: []
---

# Install Caracal

Canonical URL: https://docs.caracal.run/v1.0/get-started/install-caracal/
Markdown URL: https://docs.caracal.run/markdown/v1.0/get-started/install-caracal.md
Description: Install the caracal CLI, verify Docker, and start the local stack that the rest of Get Started uses.
Page type: workflow
Concepts: none
Requires: none

---

import { Tabs, TabItem } from '@astrojs/starlight/components'

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.

<Tabs syncKey="os">
  <TabItem label="Linux / macOS">
    ```sh
    curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install.sh | sh -s -- --version v1.0.0
    ```
  </TabItem>

  <TabItem label="Windows">
    ```powershell
    $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.
  </TabItem>
</Tabs>

Prefer to download and verify manually? Each [release](https://github.com/Garudex-Labs/caracal/releases) 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`):

<Tabs syncKey="os">
  <TabItem label="Linux / macOS">
    ```sh
    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`.
  </TabItem>

  <TabItem label="Windows">
    ```powershell
    $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.
  </TabItem>
</Tabs>

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](/v1.0/security/verify-releases/).

## Verify the Installation

The same command works in every shell:

```sh
caracal --version
```

It should print the installed version without errors.

## Verify Docker

```sh
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

```sh
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](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:

```sh
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](/v1.0/runtime-console/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](/v1.0/operations/env-vars/#the-operator-env-file) - 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](https://console.cloud.google.com/apis/credentials) or [GitHub developer settings](https://github.com/settings/developers), 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](/v1.0/operations/env-vars/#web-console-bff).

:::note[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](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](/v1.0/get-started/first-protected-call/).