---
title: Installation
description: Install the CLI, run the OSS stack with Docker, or pull SDK packages.
pageType: workflow
---

This page covers installing the `caracal` CLI, the `caracal-tui` terminal UI, and the SDK packages for TypeScript, Python, and Go.

## Install the CLI or TUI

The CLI and TUI are distributed as separate self-contained binaries for Linux, macOS, and Windows. No runtime is required. Run both installers to install both tools, or run only the TUI installer when you want `caracal-tui` without `caracal-cli`.

### Linux and macOS

```sh
# CLI
curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-cli.sh | sh

# TUI
curl -fsSL https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-tui.sh | sh
```

Each script:

1. Detects your OS and CPU architecture.
2. Downloads the matching `caracal` shell plus either `caracal-cli` or `caracal-tui` from the latest GitHub release.
3. Verifies each binary against the published `SHA256SUMS` file.
4. Installs binaries to `~/.local/bin` by default.

Supported platforms:

| OS | Architectures |
| -- | ------------- |
| Linux | `x64`, `arm64` |
| macOS | `x64`, `arm64` |
| Windows | `x64` |

**Environment variables that affect the install script:**

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `CARACAL_VERSION` | `latest` | Specific release tag to download, e.g. `v2026.05.01` |
| `CARACAL_INSTALL_DIR` | `~/.local/bin` | Directory to install binaries into |

After installation, ensure `~/.local/bin` is on your `PATH`:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

Verify the binaries you installed:

```sh
caracal --version
caracal-cli --version   # CLI installer
caracal-tui --version   # TUI installer
```

### Windows

```powershell
# CLI
irm https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-cli.ps1 | iex

# TUI
irm https://raw.githubusercontent.com/Garudex-Labs/caracal/main/install-tui.ps1 | iex
```

Binaries are placed in `%LOCALAPPDATA%\Programs\caracal` by default. Set `$env:CARACAL_INSTALL_DIR` to override. Only `x64` is available on Windows.

### Build from source

If you prefer to build from the repository:

```sh
git clone https://github.com/Garudex-Labs/caracal.git
cd caracal
pnpm install
pnpm --filter @caracalai/cli build
# Output: apps/cli/dist/caracal-cli-<os>-<arch>
```

Building requires [Bun](https://bun.sh/) and pnpm 11.1.1.

---

## Install SDK packages

Install only the packages your application uses.

### TypeScript

```sh
npm install @caracalai/sdk
# or
pnpm add @caracalai/sdk
```

Additional packages for specific use cases:

```sh
# MCP server protection
npm install @caracalai/transport-mcp

# Express middleware
npm install @caracalai/sdk @caracalai/mcp-express

# Admin API access (for provisioning scripts)
npm install @caracalai/admin
```

All `@caracalai/*` packages require **Node.js 24+**.

### Python

```sh
pip install caracalai-sdk
```

For FastMCP integration:

```sh
pip install caracalai-sdk caracalai-mcp-fastmcp
```

All `caracalai-*` packages require **Python 3.14+**.

### Go

```sh
go get github.com/garudex-labs/caracal/packages/sdk/go
```

For the net/http middleware connector:

```sh
go get github.com/garudex-labs/caracal/packages/connectors/nethttp/go
```

Requires **Go 1.26+**.

---

## Stack prerequisites

Running the Caracal OSS stack locally requires Docker 24+ with the Compose v2 plugin. Check your version:

```sh
docker compose version
```

The stack uses PostgreSQL 18 and Redis 7. Both are included as pre-built images in the Docker Compose configuration — you do not need to install them separately.

---

## Next step

Once the CLI is installed, go to [Quickstart](./quickstart/) to bring up the full stack.
