Installation

Quick start

Option 1: CLI Wizard (Recommended)

The fastest way to get started. The interactive wizard walks you through database, storage, and AI provider setup:

npx create-opencauldron@latest

It clones the repo, generates your .env.local with the values you provide, installs dependencies, and initializes git. Follow the printed next steps to start your dev server.

See the CLI Wizard docs for the full walkthrough.

Option 2: Git Clone

For manual setup or if you prefer to configure .env.local yourself:

git clone https://github.com/opencauldron/opencauldron
cd opencauldron
bun install
cp .env.example .env.local

Edit .env.local with your keys, then:

docker compose up db -d   # start local Postgres
bun run db:push           # create tables
bun tsx src/lib/db/seed-badges.ts  # seed feats
bun run dev

OpenCauldron will be available at http://localhost:3000.

Option 3: Docker

git clone https://github.com/opencauldron/opencauldron
cd opencauldron
cp .env.example .env.local    # edit with your keys
docker compose up

Prerequisites

Both the CLI wizard and manual setup require:

• Node.js 20+ or Bun 1.0+
• Docker (for local Postgres) or a Neon database
• A Google Cloud project for OAuth (setup guide)
• At least one AI model API key

Next steps

• CLI Wizard — Detailed guide for the interactive setup wizard
• Configuration — All environment variables and options
• API Keys — How to get keys for each AI provider