open-webui-ai4me/AGENTS.md

Open WebUI - Agent Instructions

Quick Commands

# Frontend
npm install                    # Install dependencies
npm run pyodide:fetch          # Required! Fetch Pyodide before dev
npm run dev                    # Dev server (port 5173)
npm run dev:5050               # Alternative dev server (port 5050)
npm run build                  # Build frontend
npm run test:frontend          # Run vitest
npm run check                  # Typecheck (one-time)
npm run check:watch            # Typecheck (watch mode)
npm run lint:frontend          # ESLint frontend
npm run format                 # Prettier (frontend)

# Backend
./backend/dev.sh               # Dev server (port 8080)
uvicorn open_webui.main:app    # Manual backend start
npm run lint:backend           # Pylint backend
npm run format:backend         # Ruff format backend
pytest                         # Backend tests (from backend/open_webui/)

# Full stack
npm run lint                   # Full lint (frontend + types + backend)
npm run format                 # Full format

# Docker
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Critical Constraints

Python: 3.11 or 3.12 only (NOT 3.13+) Node: 18.13.0 - 22.x.x (enforced in package.json) Pyodide: MUST fetch first (npm run pyodide:fetch) - required for code interpreter

Architecture

Monorepo: SvelteKit frontend + FastAPI backend

• Frontend (/src): Svelte 5, SvelteKit, Vite

  • Components: /src/lib/components
  • API clients: /src/lib/apis
  • Stores: /src/lib/stores
  • Utils: /src/lib/utils

• Backend (/backend/open_webui): FastAPI, SQLAlchemy

  • Routers: /backend/open_webui/routers
  • Models: /backend/open_webui/models
  • Utils: /backend/open_webui/utils
  • Config: /backend/open_webui/config.py
  • Migrations: /backend/open_webui/migrations/

Key Development Patterns

Adding a new API endpoint:

1. Define Pydantic model in backend/open_webui/routers/ (e.g., configs.py, openai.py)
2. Add @router decorator function
3. Import router in backend/open_webui/main.py via app.include_router()
4. Create frontend client in /src/lib/apis/

Adding a new model/preset:

• Admin Panel → Settings → Models → Create Model
• Or /backend/open_webui/models/models.py schema

Adding translations:

1. Add key to translation files (e.g., /src/locales/en.json)
2. Run npm run i18n:parse to sync
3. Use $t('key') in templates

Adding a new UI component:

• Create in /src/lib/components/ structure matching parent
• Use Svelte 5 runes ($state, $derived, $effect)
• Export types in /src/lib/types.ts

Environment Variables

Required defaults (auto-generated if not set):

• OLLAMA_BASE_URL='http://localhost:11434'
• OPENAI_API_BASE_URL=''
• OPENAI_API_KEY=''
• CORS_ALLOW_ORIGIN='*'
• FORWARDED_ALLOW_IPS='*'

Critical for Docker:

• --add-host=host.docker.internal:host-gateway (macOS/Linux - required for container → host communication)
• -v open-webui:/app/backend/data (persist webui.db)

Testing

• Unit tests (frontend): npm run test:frontend (vitest)
• E2E tests: npm run cy:open (Cypress UI)
• Backend tests: pytest from /backend/open_webui/test/
• Note: Integration tests may require running services (Ollama, vector DBs)

Formatting / Linting

Pre-commit hooks: ruff (fix) + ruff-format (backend only)

# Full format
npm run format         # Frontend (prettier)
npm run format:backend # Backend (ruff format)

# Full lint
npm run lint:frontend  # ESLint
npm run lint:backend   # Pylint
npm run check          # Typecheck

Migrations

SQLite default (webui.db). PostgreSQL/MySQL supported.

# After code change affecting DB schema
cd backend/open_webui
DATABASE_URL=sqlite:///webui.db alembic revision --autogenerate -m "description"

Known Gotchas

1. pyodide:fetch not run → Code interpreter fails silently
2. Docker on macOS → Missing --add-host=host.docker.internal:host-gateway → Backend cannot reach Ollama
3. Python 3.13+ → Dependencies incompatible
4. OpenAI URLs trailing slash → Normalize with .rstrip('/') before use
5. Custom API endpoints → Use backend proxy for credentials security (see back/open_webui/routers/configs.py line 709)

File Ownership

Directory	Purpose
/backend/open_webui/routers	API endpoints
/backend/open_webui/models	Pydantic + SQLAlchemy models
/backend/open_webui/models/*.py	DB schemas (ChatModel, UserModel, etc.)
/backend/open_webui/config.py	Persistent config (OPENAI_API_BASE_URLS, etc.)
/src/lib/apis/*	Frontend API clients
/src/lib/components	Svelte components
/src/lib/stores	Svelte stores
/cypress/e2e	E2E test specs
/scripts	Dev scripts

CI Workflows

• docker-build.yaml → Multi-platform Docker images
• build-release.yml → Release trigger (package.json change)
• format-backend.yaml → Python formatting (ruff) on backend changes
• format-build-frontend.yaml → Frontend format + build + vitest