---
title: Local Setup
description: Toolchains, package managers, and one-command bootstrap for Caracal development.
pageType: workflow
---

This page covers what you need installed and how to bring up a local Caracal stack ready for development.

---

## Required toolchains

| Tool | Version | Used for |
| --- | --- | --- |
| Node.js | 24+ | TypeScript services and packages |
| pnpm | 11.1.1 | TypeScript dependency management |
| Go | 1.26+ | Go services and packages |
| Python | 3.14+ | Python SDK packages |
| Bun | 1.x | CLI/TUI binary compilation |
| Docker Desktop | latest stable | Local service stack |

Install each from its official source. The repository does not manage toolchain versions through scripts — use your system package manager or version manager.

### Go workspace

The repository uses a `go.work` file at the repository root to span all 11 Go modules. After installing Go 1.26+, no additional configuration is needed — `go` commands run from the repo root pick up all modules automatically.

```sh
go work sync   # sync workspace module graph
```

### Python environments

Each Python package has its own virtual environment. Create it before working on that package:

```sh
cd packages/sdk/python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

---

## Clone and install

```sh
git clone https://github.com/garudex-labs/caracal.git
cd caracal
pnpm install
```

`pnpm install` resolves all TypeScript workspace dependencies across `apps/`, `services/`, `packages/`, and `docs/`. Go and Python dependencies are managed separately per module.

---

## Environment configuration

Credentials are bootstrapped automatically the first time you run `caracal up`.
No manual `.env` editing is required.

The bootstrap (shared by dev, rc, and stable):

1. Generates random secret files in `infra/secrets/files/` (gitignored, `0444`) for Postgres, Redis, the admin token, zone KEK, and HMAC keys.
2. Services consume those secrets exclusively through the `*_FILE` convention — no secret values are written to any `.env` file.

`infra/docker/dev.env` is committed and rendered from `packages/engine/src/envSchema.ts`; do not edit it by hand. To override defaults, copy `infra/docker/local.env.example` to `infra/docker/local.env` (gitignored) and edit it. Compose loads `dev.env` first then `local.env`, so local entries win.

Idempotent and safe to re-run — existing secret files are reused.

If you want to provision credentials without starting the stack, run:

```sh
pnpm secrets:init
```

After changing the schema, regenerate `dev.env` with `node packages/engine/scripts/render-dev-env.mjs`. CI runs the same script with `--check` to fail on drift.

Do not commit `infra/docker/local.env` or `infra/secrets/files/` — both are in `.gitignore`.

---

## Start the stack

```sh
caracal up
```

This runs `docker compose up -d` using the compose file in `infra/docker/`. It starts five core application services: API (3000), STS (8080), Gateway (8081), Coordinator (4000), Audit (9090), plus PostgreSQL, Redis, and one-shot initialization containers.

After the stack is up, provision a zone and application against the running control-plane API:

```sh
caracal zone create --name dev
caracal app create --zone <zone-id> --name dev-app
```

`caracal app create` prints the client secret on creation — save it into `caracal.toml` along with the zone ID and STS URL. The CLI discovers `CARACAL_ADMIN_TOKEN` from `infra/secrets/files/caracalAdminToken` (dev, via `CARACAL_REPO_ROOT`) or `$CARACAL_HOME/secrets/caracalAdminToken` (installed); pass `--admin-token` or export `CARACAL_ADMIN_TOKEN` to override.

See [Configuration File](../cli-tui/config-file/) for the full `caracal.toml` schema.

Verify the stack is healthy:

```sh
caracal status
```

The five application services plus PostgreSQL and Redis should show `ok`.

---

## Database migrations

Migrations run automatically when the API service starts. Migration files live in `infra/postgres/migrations/` as numbered SQL files:

```
NNNN_description.up.sql
NNNN_description.down.sql
```

If you need to run migrations manually against a local Postgres instance:

```sh
psql $DATABASE_URL -f infra/postgres/migrations/0001_init.up.sql
```

The API uses an advisory lock to serialize migration runs across concurrent replicas, so it is safe to start multiple replicas simultaneously.

---

## Build individual services

**TypeScript services:**

```sh
pnpm --filter @caracalai/api build
pnpm --filter @caracalai/coordinator build
```

**Go services:**

```sh
cd services/sts && go build ./...
cd services/gateway && go build ./...
cd services/audit && go build ./...
```

**CLI/TUI binaries:**

```sh
pnpm --filter @caracalai/cli build
pnpm --filter @caracalai/tui build
# Binaries land in apps/cli/dist/caracal-cli-<os>-<arch> and apps/tui/dist/caracal-tui-<os>-<arch>
```

---

## Editor setup

The repository has no enforced editor configuration. Recommended plugins:

- **TypeScript**: the built-in TS Language Server via your editor's LSP support.
- **Go**: `gopls` (bundled with Go or installable via `go install golang.org/x/tools/gopls@latest`).
- **Python**: Pylance or Pyright.
- **Rego**: OPA extension for VS Code provides syntax highlighting and `opa check` integration.
