Skip to main content

​
Quickstart

run the stack

​
From clone to first edit

This guide gets Iris from repository checkout to a working local editor as quickly as possible, with the minimum environment needed to upload a clip and test a localized edit.

you need
  • Node.js 20+
  • Python 3.11+
  • FFmpeg and FFprobe
  • A repo-root .env
The happy path is: install frontend dependencies, start the frontend, start the backend, verify health, then upload a clip and test one localized edit.

​
Frontend

Vite and React app for landing, projects, and the active editing surface.

​
Backend

FastAPI service for uploads, projects, generation, masking, narration, and export.

​
Media stack

FFmpeg and FFprobe bridge uploaded video into actual editorial operations.

​
Know the layout

The repo is split by responsibility:
  • frontend/ for the Vite and React app
  • backend/ for the FastAPI service and worker orchestration
  • ai/ for provider adapters and prompts
  • gpu-worker/ for optional segmentation and vision support
  • infra/ for Docker Compose and deployment helpers
boot sequence

​
Start Iris locally

Keep the frontend and backend as separate processes. The frontend renders the editor. The backend handles uploads, jobs, metadata, and AI-heavy routes.

1

Install frontend dependencies

npm install --prefix frontend
2

Start the frontend

npm run dev
The frontend runs on http://localhost:3000.
3

Start the backend

Run the FastAPI backend with the repo-root environment loaded.
cd backend && uvicorn app.main:app --reload --port 8000
The backend serves uploads, projects, generation, identify, mask, propagation, narration, and export on http://localhost:8000.
4

Verify health

curl http://localhost:8000/api/health
curl http://localhost:8000/api/ai/health
Open http://localhost:3000 once both checks are green.
first run

​
Make one real edit

  1. Open the editor.
  2. Upload a source clip.
  3. Scrub to a moment you want to change.
  4. Draw a box around the subject or region.
  5. Prompt a change.
  6. Review the generated options.
  7. Accept one result and continue editing.

​
Environment

The repo-root .env powers both browser and backend behavior.

​
AI mode

Stub mode is enough for local work. Real demo paths want provider keys and reachable workers.

​
Verification

Use health endpoints and typecheck commands before debugging the editor itself.

Fastest local path: frontend on port 3000, backend on port 8000, health checks green, then one upload and one accepted edit.

​
What the backend needs

The backend is not just an API shell. It depends on real media tooling.

​
Required for the local stack

  • Python environment and dependencies
  • Environment variables from the repo root
  • FFmpeg and FFprobe for upload probing and media transforms

​
Optional but important for the full experience

  • Real provider keys instead of stub mode
  • Object storage for durable media URLs
  • GPU worker for segmentation-heavy flows

​
Common verification commands

npm run lint
curl http://localhost:8000/api/health
curl http://localhost:8000/api/ai/health

​
Optional: the CLI

Iris includes a command-line interface in the cli/ directory that wraps the backend API. You can use it to list projects, upload clips, and trigger edits from your terminal. It also supports multi-agent video analysis for batch workflows.