# PolyLLM

**One interface. Every model. Bring your own keys.** — https://www.polyllm.io

PolyLLM is a mobile-first, multi-model AI workspace — an "AI operating system" rather than a chat box: connect your own
OpenAI, Anthropic, Google Gemini, xAI, Mistral, DeepSeek, Kimi (Moonshot), OpenRouter and Cerebras API keys (plus any
OpenAI-compatible endpoint such as Ollama, LM Studio, vLLM, llama.cpp or MLX), discover the models your keys can reach,
configure each one with only the parameters it supports, chat with real token-by-token streaming, let the transparent
**Smart Router (AUTO)** recommend a model, compare 2–4 models inline or in the **Arena** (blind mode, votes per criterion,
personal scoreboard), organise work in **Projects** with a prompt library (`{{variables}}`) and a reusable file library,
search everything (`model:claude project:research after:2026-08-01`), share/export conversations, and track tokens,
latency, cost, projections and savings opportunities in **Usage**. Installable as a PWA; designed first for 375–430 px
phones (bottom navigation, bottom sheets, swipe gestures, keyboard-safe composer), then tablet and desktop. Keys are encrypted at rest (AES-256-GCM, HKDF-derived data key, AAD-bound to the user) and only decrypted on the
server immediately before a provider request.

## Stack
Next.js 16 (App Router, Route Handlers with SSE streaming) · React 19 · TypeScript · Tailwind v4 · PostgreSQL 17 + Drizzle ·
Better Auth 1.7 (Argon2id, email verification, sessions, reset, change email, delete account) · Resend · Zod ·
official provider SDKs (`openai`, `@anthropic-ai/sdk`, `@google/genai`); xAI, Mistral, DeepSeek, Kimi, OpenRouter and Cerebras through the OpenAI SDK pointed at their endpoints with per-provider body translation (`providers/shared/openai-compat`).

## Layout
```
src/app                 routes: (marketing) landing/legal · (auth) login/signup/verify/reset · app/* workspace · admin/* · share/[id] · api/*
src/lib/ai/core         provider-neutral contract: PolyModel, UnifiedChatRequest, UnifiedStreamEvent, errors, retry, pricing, normalization
src/lib/ai/providers    adapters (openai, anthropic, gemini, xai, mistral, deepseek, kimi, openrouter, cerebras) + catalogs — provider quirks live ONLY here
src/lib/ai/registry     model registry: live listing → catalog merge → Postgres; scheduled + manual sync
src/lib/chat            turn orchestration (edit/regenerate/continue/branch/adopt, ephemeral temporary chats), built-in tools loop, SSE
src/lib/arena           sessions, streaming per model, votes/criteria, winner & scoreboard math, exports, public shares
src/lib/projects|library|prompts   workspaces, reusable files (token estimates), prompt templates with variables
src/lib/search          full-text search (Postgres FTS + filter query language) · src/lib/export conversation exports (md/txt/json/html→print)
src/lib/endpoints       custom OpenAI-compatible endpoints (encrypted keys/headers, discovery, SSRF guard) · src/lib/usage analytics & savings
src/lib/models          model intelligence: badges, lifecycle, intent search, compare slugs, parameter groups · src/lib/client router & token estimators
src/lib/providers       encrypted key storage & validation
src/db                  schema.ts (core) + schema-workspace.ts (1.0 tables) · drizzle/ migrations
src/components          ui kit (sheet, segmented, …) · app shell (bottom nav, drawer) · chat · models · arena · projects · library · prompts · search · share · usage · providers · settings · marketing
docs/                   UPGRADE-PLAN (1.0 contract) + upgrade-notes/ (per area) · provider-research · provider-test-matrix · deployment-cluster · UI brief
scripts/                sync-models, provider-matrix (real-API tests), brand-assets (favicons / PWA icons / OG image)
e2e/, tests/, qa/       Playwright workflows, vitest unit + integration tests, responsive QA sweeps (`qa/responsive-qa.mjs`, `qa/flows.mjs`)
```

## Development
```bash
cp .env.example .env            # fill AUTH_SECRET, API_KEY_ENCRYPTION_SECRET, RESEND_API_KEY, owner provider keys (optional)
createdb polyllm && pnpm install && pnpm db:migrate
pnpm models:sync                # populate the registry with the owner keys
pnpm dev                        # http://localhost:3000
pnpm typecheck && pnpm lint && pnpm test
pnpm providers:matrix           # real-API capability matrix → docs/provider-test-matrix.md
EMAIL_DRY_RUN=1 EMAIL_DRY_RUN_PRINT=1 pnpm dev && pnpm test:e2e   # full browser workflow (links read from the dev log)
```

## Responsive QA
```bash
pnpm dev                                                    # single dev server on :3000
QA_EMAIL=… QA_PASSWORD=… node qa/responsive-qa.mjs          # 17 screens × 375/390/393/430/tablet/desktop → qa/out/ + report.json
node qa/flows.mjs --width=390 [--send]                      # drawer, model picker, composer, chat, Arena swipe, search, palette, sheets
```

## Deployment
Runs on the private MacLustr cluster behind the MacLustr Tunnel (WireGuard + Caddy on BHS64) — see `docs/deployment-cluster.md`.
Built and hosted by Simon-Pierre Boucher on [MacLustr](https://www.maclustr.io) · contact@spboucher.ai

## Security notes
No provider key ever reaches the browser, logs or analytics (structured logger redacts key-shaped strings and sensitive
field names). CSP, HSTS, HttpOnly/SameSite cookies, rate limits on auth and provider endpoints, per-user audit log.