Skip to main content

​
Local Development

environment

​
Run the full stack locally

Iris runs as two processes locally: a Vite frontend on port 3000 and a FastAPI backend on port 8000. Both read from a shared .env at the repo root.

prerequisites
  • Node.js 20+ or Bun
  • Python 3.11+
  • FFmpeg + FFprobe
  • PostgreSQL (or Docker)

​
Environment variables

Create a .env file at the repo root. See .env.example for the full list. Key variables:
VariablePurposeRequired
GEMINI_API_KEYGemini vision + text generationYes (or use stubs)
DATABASE_URLPostgreSQL connection stringYes
USE_AI_STUBStrue for offline dev, false for real AINo (defaults to true)
VULTR_ACCESS_KEY / VULTR_SECRET_KEYObject storage for mediaNo (local storage fallback)
SUPABASE_URL / SUPABASE_JWT_SECRETAuthenticationNo (anon sessions work)
VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEYFrontend auth clientNo
GPU_WORKER_URLSAM2 segmentation workerNo
ELEVENLABS_API_KEYTTS narrationNo

​
Starting the frontend

cd frontend
bun install
bun run dev
Runs on http://localhost:3000.

​
Starting the backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Or use the helper script: 
./scripts/dev_backend.sh
Runs on http://localhost:8000.

​
Docker alternative

cd infra
docker compose up --build
This starts frontend, backend, and PostgreSQL together. The backend runs on port 8000, frontend on port 3000.

​
Stub mode

Set USE_AI_STUBS=true in your .env to run without any API keys. All AI calls return deterministic placeholder responses. Good for UI development and testing.

​
Iris CLI (optional)

cd cli
pip install -e .
iris auth status
The CLI wraps the backend API for scripting and agent-driven editing. See CLI reference for all commands.

​
Verification

curl http://localhost:8000/api/health
curl http://localhost:8000/api/ai/health
npx tsc --noEmit --project frontend
All three should pass before you start developing.