# PolyLLM

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

PolyLLM is a universal control center for AI models: connect your own OpenAI, Anthropic, Google Gemini, xAI, Mistral, DeepSeek, Kimi (Moonshot), OpenRouter and Cerebras API keys,
discover the models your keys can reach, configure each one with only the parameters it supports, chat with real
token-by-token streaming, compare up to four models side by side in the Arena, and track tokens, latency and estimated
cost. 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), built-in tools loop, SSE
src/lib/providers       encrypted key storage & validation
src/components          ui kit · app shell · chat · arena · settings · marketing
docs/                   provider-research (per provider, dated), provider-test-matrix (generated), deployment-cluster, final-audit, UI brief
scripts/                sync-models, provider-matrix (real-API tests)
e2e/, tests/            Playwright workflows, vitest unit tests
```

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

## Deployment
Runs on the private MacLustr cluster behind ngrok — see `docs/deployment-cluster.md`.

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