Development Setup

Set up a local development environment for contributing to Elmo.

Prerequisites

Node.js 24.x

pnpm 10.x+ (required — npm and yarn are not supported)

PostgreSQL 15+ (or use Docker)

Docker (for running the full stack locally)

git clone https://github.com/elmohq/elmo.git
cd elmo
pnpm install

Copy the example environment file and fill in your values:

cp .env.example .env

At minimum, you need:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`BETTER_AUTH_SECRET`	Any random string for session encryption

Add AI provider API keys if you want to test visibility tracking:

Variable	Description
`OPENAI_API_KEY`	For ChatGPT tracking
`ANTHROPIC_API_KEY`	For Claude tracking

Run Drizzle migrations to create the schema:

cd apps/web
pnpm drizzle-kit migrate

Run all development servers in parallel:

pnpm dev

This starts:

Web app at http://localhost:3000

Worker process for background jobs

Or run only the web app:

pnpm --filter @workspace/web dev

For a setup closer to production, use the CLI in dev mode:

# Build from local source instead of pulling images
elmo init --dev

# Rebuild after code changes
elmo compose build
elmo compose up -d

The Docker build uses a multi-stage docker/Dockerfile with separate targets for web and worker.

Elmo uses Ladle for component development in isolation:

pnpm --filter @workspace/web ladle

Stories live in apps/web/src/stories/ and cover the app sidebar, prompt charts, and other components across deployment modes.

Was this page helpful?