Developer Guide

Getting Started

Set up OpenStory for local development

OpenStory is an open-source AI video production platform. This guide walks you through setting up a local development environment.

Prerequisites

Nothing else. No Docker, no external database, no Cloudflare account — local dev runs the full stack (D1, R2, Workflows, Durable Objects, email) inside Workerd via Miniflare.

Quick Start

# Clone the repository
git clone https://github.com/UllrAI/openstory.git
cd openstory

# Install and run
bun install
bun dev

bun dev does everything: it generates .env.local (with auth/encryption secrets) on first run, migrates and seeds the local database, and starts the dev server.

The app will be available at http://localhost:3000.

AI Keys

The default generation path only needs a fal.ai key. Run bun setup to add fal.ai and OpenRouter keys interactively, or paste any provider key into .env.local:

  • FAL_KEY — fal.ai for image, video, audio, and fal-routed LLM calls
  • OPENROUTER_KEY — optional direct OpenRouter access for LLM calls

Environment Variables

See .env.example for the full list of available environment variables, including optional services like Google OAuth, Stripe, PostHog, and remote R2 storage.

Language

The interface supports English and Simplified Chinese. Choose a language on the sign-in screen or from the app sidebar. The choice is stored in a cookie and is shared by server-rendered and browser-rendered views; on a first visit, OpenStory uses the browser's preferred language.

Built-in style, talent, and location names and descriptions are translated. User-created content remains in the language in which it was entered. See the internationalization guide for development conventions.

Database

Local development uses a Cloudflare D1 database (Miniflare-backed SQLite) via Drizzle ORM — no account or remote service required. bun dev migrates and seeds it automatically.

# Generate migrations from schema changes
bun db:generate

# Apply migrations to the local D1 database
bun db:migrate:local

# Open Drizzle Studio against the local D1 database
bun db:studio:local

Production deployments use Cloudflare Workers, D1, R2, Workflows, and Durable Objects. See the Cloudflare deployment guide for details. Local development does not require a Cloudflare account, but the current production architecture is Cloudflare-specific.

Next Steps