open-webui-ai4me/AGENTS.md

# Open WebUI - Agent Instructions

## Quick Commands

```bash
# 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)

```bash
# 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.

```bash
# 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