Run the OpenCut Background Remover Locally

The background remover ships as a Python FastAPI service alongside the web app.

Setup

cd apps/bg-remover
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Download model weights (U^2-Net, SAM) using the provided script:

python scripts/download_models.py

Run the service

uvicorn app.main:app --host 0.0.0.0 --port 8001

Configure the web app

apps/web/.env.local:

BACKGROUND_REMOVER_URL="http://localhost:8001"

Restart bun dev so the Next.js API routes use the local endpoint.

Diagram

  sequenceDiagram
    participant UI as OpenCut UI
    participant API as Next.js API route
    participant BR as Background remover
    UI->>API: POST /api/background/remove
    API->>BR: POST /mask
    BR-->>API: Mask PNG
    API-->>UI: Processed frame data

Run the service behind docker-compose in production to manage dependencies consistently.