Installation

There are three ways to run OpenCauldron, depending on what you’re trying to do.

You want to…	Use
Run OpenCauldron for your team	Docker self-host (below) — the default for almost everyone
Contribute to OpenCauldron itself	Contributor setup
Build a custom studio on top of OpenCauldron	Scaffold your own fork

Self-host with Docker

The recommended path for anyone running OpenCauldron as-is. No clone, no Node, no package manager — just Docker.

Prerequisites

Docker and Docker Compose
A Google Cloud project with an OAuth 2.0 client ID (see Setting up Google OAuth)
API keys for whichever AI providers you want to enable (all optional — models without keys are hidden)

Install

curl -O https://raw.githubusercontent.com/opencauldron/opencauldron/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/opencauldron/opencauldron/main/.env.example
# Edit .env: set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, WORKSPACE_NAME, ADMIN_EMAIL
docker compose up -d
open http://localhost:3000

That’s the whole install. On first boot the container:

Auto-generates a persistent NEXTAUTH_SECRET and stores it in a named volume (so it survives upgrades).
Waits for Postgres to be ready, then applies all database migrations.
Bootstraps the admin workspace from WORKSPACE_NAME and ADMIN_EMAIL if both are set.
Starts the Next.js server.

Upgrading

docker compose pull && docker compose up -d

Migrations run automatically on container start. Your data, uploads, and the persisted auth secret all live in named volumes and survive image upgrades. See the GHCR releases page for the changelog.

What’s bundled

The default docker-compose.yml ships:

The OpenCauldron app (pulled from ghcr.io/opencauldron/opencauldron:latest, multi-arch)
A Postgres 16 + pgvector container
Named volumes for the database, uploaded media, and the auth secret

If you’d rather use Neon for the database or Cloudflare R2 for storage, set the relevant variables in .env — the app auto-detects them. See Configuration for the full list.

Contributor setup

For day-to-day work on OpenCauldron itself. HMR works, host tooling (psql, drizzle-kit studio, IDE plugins) connects directly to the DB, no rebuild loop.

Prerequisites

Node.js 20+ and pnpm
Docker (for the local Postgres) — or any reachable Postgres with pgvector

Install

git clone https://github.com/opencauldron/opencauldron
cd opencauldron
pnpm install
cp .env.example .env.local                       # then edit with your keys
docker compose -f docker-compose.dev.yml up -d   # local Postgres on :5432
pnpm exec drizzle-kit migrate                    # apply the SQL migrations
pnpm run dev

Open http://localhost:3000.

To validate the production Docker path (entrypoint, migration runner, healthcheck) before opening a PR, uncomment the app service block at the bottom of docker-compose.dev.yml and re-run the same command.

See the contributing guide for code style, testing conventions, and how to add new AI providers.

Scaffold your own fork

If you want to build a custom studio on top of OpenCauldron — your own branding, your own features, your own deploy — clone the repo and run the setup wizard:

git clone https://github.com/opencauldron/opencauldron.git my-studio
cd my-studio
pnpm install
pnpm setup

This is not the right path for running OpenCauldron as-is. Use Docker for that. The wizard is for developers who want to take the codebase, modify it, and ship their own version.

The wizard walks you through database, storage, and AI provider setup, then writes a configured .env.local. It does not clone, install, or detach git history — those are your call. To start from a clean slate after cloning: rm -rf .git && git init.

See the Setup Wizard reference for the full walkthrough.

Next steps

Configuration — All environment variables and options
API Keys — How to get keys for each AI provider
Storage — Configure local filesystem or Cloudflare R2
Database — Migrations, schema, and Neon vs Postgres