Self-Hosting Guide

LoreKit is MIT licensed. Run it locally with your own API keys — no account needed, no credits, no limits.

Prerequisites#

Requirement	Notes
Python 3.11+	Backend server and AI pipeline
Node.js 20+	Frontend build and Drizzle ORM migrations
PostgreSQL 15+	With pgvector extension for embeddings
OpenAI API key	Story generation (LLM)
fal.ai API key	Image, video, and TTS generation

Quick Start#

bash

# Clone the repo
git clone https://github.com/anthropics/lorekit
cd lorekit

# Install Python dependencies
pip install -e .

# Install frontend dependencies
cd web && npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys (OPENAI_API_KEY, FAL_KEY)

Database Setup#

bash

# Create the PostgreSQL database
createdb lorekit

# Apply schema migrations
cd web
npm run db:deploy

This uses Drizzle ORM to create all 14 tables including pgvector indexes.

Running#

bash

# Terminal 1: Start the backend (port 8001)
python -m lorekit.server

# Terminal 2: Start the frontend (port 3001)
cd web && npm run dev

Open localhost:3001 to use the web app, or connect Claude via MCP (see Getting Started).

Environment Variables#

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://localhost:5432/lorekit
OPENAI_API_KEY	OpenAI API key for story generation	sk-...
FAL_KEY	fal.ai API key for image/video/TTS	fal-...
LLM_PROVIDER	LLM provider (openai or anthropic)	openai
LLM_MODEL	Model name	gpt-5.4

Database Migrations#

Schema changes are managed by Drizzle ORM. After updating the schema:

bash

cd web
npm run db:generate   # Generate migration SQL from schema changes
npm run db:migrate    # Apply migrations
npm run db:studio     # Visual database browser (optional)

Never use drizzle-kit push — it silently deletes RLS policies. Always use generate + migrate.