# 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

text

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 · 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.