Local Development

Running OpenReels locally gives you faster iteration with hot reloading and direct access to the source code. This guide covers both development mode and production-like local runs.

Prerequisites

ffprobe is used for audio duration detection during the pipeline. Without it, the assembly stage will fail.

Install

git clone https://github.com/tsensei/OpenReels.git
cd OpenReels
pnpm install

This installs dependencies for the root package and the web/ workspace.

Environment Setup

cp .env.example .env

Edit .env with your API keys. At minimum you need one LLM key and one TTS key (or use kokoro for free local TTS). See API Keys for details.

CLI Mode

The fastest way to generate a video locally:

pnpm start "The history of coffee"

This runs the full pipeline: research, director, TTS, visuals, assembly, and critic. Output goes to ./output/ by default.

Equivalent command with explicit flags:

npx tsx --env-file=.env src/index.ts "The history of coffee"

Useful CLI Flags

# Dry run (skip rendering, produce DirectorScore only)
pnpm start "topic" --dry-run

# Skip music
pnpm start "topic" --no-music

# Skip AI video generation
pnpm start "topic" --no-video

# Choose providers
pnpm start "topic" --llm gemini --tts kokoro --image openai

# Auto-confirm cost estimate (non-interactive)
pnpm start "topic" --yes

# Custom output directory
pnpm start "topic" -o ./my-output

Web UI Mode

Running the web UI locally requires Redis and three processes: the API server, the worker, and the Vite dev server.

Start Redis

# macOS
brew services start redis

# Or run directly
redis-server

Option A: Docker Compose (Recommended)

The simplest way even for local dev:

docker compose up

Option B: Manual Processes

Run each in a separate terminal:

Terminal 1 — API Server

npx tsx --env-file=.env src/server.ts

Terminal 2 — Worker

npx tsx --env-file=.env src/worker.ts

Terminal 3 — Web Dev Server (optional, for frontend development)

cd web
npx vite

The API server serves the pre-built frontend from web/dist/. If you are developing the frontend, run Vite's dev server for hot reloading and proxy API requests to port 3000.

Build

TypeScript Build

pnpm build

Uses tsup to compile TypeScript to dist/. The compiled CLI is available as ./dist/index.js.

Frontend Build

cd web
npx vite build

Outputs to web/dist/. The API server automatically serves this directory when it exists.

Type Checking

pnpm typecheck

Runs tsc --noEmit to check types without emitting files.

Linting and Formatting

OpenReels uses Biome for linting and formatting:

# Check
pnpm lint

# Auto-fix
pnpm lint:fix

# Format
pnpm format

Project Scripts Reference