Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat: Premium live catalog — signed sync, license keys, self-serve billing

Tashfeen076fa69a5b0c
diff --git a/README.md b/README.md
index 90183a64..da2832c0 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ Aggregate the free tiers from Google, Groq, Cerebras, NVIDIA, Mistral, OpenRoute
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
[![Docker image](https://img.shields.io/badge/ghcr.io-freellmapi-2496ED?logo=docker&logoColor=white)](https://github.com/tashfeenahmed/freellmapi/pkgs/container/freellmapi)
+**[freellmapi.co](https://freellmapi.co)** — browse the live model catalog
+
![Fallback chain with per-provider token budget](repo-assets/fallback-chain.png)
</div>
@@ -26,6 +28,7 @@ Aggregate the free tiers from Google, Groq, Cerebras, NVIDIA, Mistral, OpenRoute
- [Quick start](#quick-start)
- [Docker](#docker)
- [Desktop app](#desktop-app)
+- [Premium (live catalog)](#premium-live-catalog)
- [Using the API](#using-the-api)
- [Screenshots](#screenshots)
- [How it works](#how-it-works)
@@ -107,10 +110,10 @@ PRs that add any of these are very welcome. See [Contributing](#contributing).
**One-liner** (Docker required — sets up `~/freellmapi`, generates an encryption key, pulls the image, and starts the container):
```bash
-curl -fsSL https://tashfeenahmed.github.io/freellmapi/install.sh | bash
+curl -fsSL https://freellmapi.co/install.sh | bash
```
-Prefer to read before you pipe to bash? [The script is here](docs/install.sh). Re-running it is safe: your `.env` (and encryption key) is preserved and the container updates to `:latest`. Override the defaults with `FREELLMAPI_DIR`, `PORT`, or `HOST_BIND` env vars.
+Prefer to read before you pipe to bash? [The script is here](https://freellmapi.co/install.sh). Re-running it is safe: your `.env` (and encryption key) is preserved and the container updates to `:latest`. Override the defaults with `FREELLMAPI_DIR`, `PORT`, or `HOST_BIND` env vars.
**Or manually with Docker Compose.** It runs the API and dashboard together on port 3001 and persists SQLite in a named volume.
@@ -201,7 +204,7 @@ request stats.
![FreeLLMAPI desktop app](repo-assets/desktop.png)
-No published binaries — it builds from this repo in a few minutes:
+**[Download the macOS app from Releases](https://github.com/tashfeenahmed/freellmapi/releases/latest)**, or build it from this repo in a few minutes:
```bash
npm install
@@ -212,6 +215,24 @@ npm run desktop:dist:win # Windows installer
> **Windows:** the build config is in place but not tested yet — if you try it,
> a quick report (working or not) in an issue would be much appreciated.
+## Premium (live catalog)
+
+The router keeps its model catalog fresh on its own: it pulls a signed catalog
+from [freellmapi.co](https://freellmapi.co) twice a day and applies new models,
+quota changes, and provider quirk fixes to your local DB (your own enable/disable
+choices and custom providers are never touched; every download is verified
+against a pinned Ed25519 key before it is applied).
+
+- **Free** installs follow a **monthly snapshot** — zero cost, forever.
+- **[Premium](https://freellmapi.co/#pricing)** ($19/yr or $49 lifetime) follows
+ the **live feed**, refreshed every 2-3 days, so new free models are in your
+ router the moment they exist. One key covers all your devices; activate it in
+ the dashboard under **Premium**. Cancel or manage billing self-serve at
+ [freellmapi.co/manage](https://freellmapi.co/manage).
+
+The catalog server never sees your prompts, completions, or provider keys — the
+router stays fully self-hosted either way.
+
Locally built apps launch without Gatekeeper/SmartScreen warnings — no code
signing involved. Full instructions in [desktop/README.md](./desktop/README.md).
diff --git a/client/dev/mockApi.ts b/client/dev/mockApi.ts
new file mode 100644
index 00000000..a63e5417
--- /dev/null
+++ b/client/dev/mockApi.ts
@@ -0,0 +1,152 @@
+import type { Plugin } from 'vite'
+
+// Dev-only in-memory mock of the /api surface the Fallback page needs, so the
+// frontend can be exercised without a running backend. Enabled only when the
+// dev server is started with MOCK_API=1 (see vite.config.ts) — never bundled.
+
+const PRESETS: Record<string, { reliability: number; speed: number; intelligence: number }> = {
+ balanced: { reliability: 0.5, speed: 0.25, intelligence: 0.25 },
+ smartest: { reliability: 0.35, speed: 0.1, intelligence: 0.55 },
+ fastest: { reliability: 0.35, speed: 0.55, intelligence: 0.1 },
+ reliable: { reliability: 0.7, speed: 0.15, intelligence: 0.15 },
+}
+
+interface MockModel {
+ modelDbId: number
+ platform: string
+ modelId: string
+ displayName: string
+ sizeLabel: string
+ intelligenceRank: number
+ speedRank: number
+ monthlyTokenBudget: string
+ supportsVision: boolean
+ rpmLimit: number | null
+ rpdLimit: number | null
+ enabled: boolean
+ priority: number
+ reliability: number
+ speed: number
+ intelligence: number
+ headroom: number
+ rateLimit: number
+ totalRequests: number
+}
+
+let strategy = 'balanced'
+// User-tuned vector for the 'custom' strategy (kept normalized, like the server).
+let customWeights = { ...PRESETS.balanced }
+
+function activeWeights() {
+ if (strategy === 'custom') return customWeights
+ return PRESETS[strategy] ?? PRESETS.balanced
+}
+
+const models: MockModel[] = [
+ { modelDbId: 1, platform: 'google', modelId: 'gemini-2.5-pro', displayName: 'Gemini 2.5 Pro', sizeLabel: 'Frontier', intelligenceRank: 1, speedRank: 8, monthlyTokenBudget: '~12M', supportsVision: true, rpmLimit: 5, rpdLimit: 100, enabled: true, priority: 1, reliability: 0.94, speed: 0.55, intelligence: 1.0, headroom: 1, rateLimit: 1, totalRequests: 412 },
+ { modelDbId: 2, platform: 'groq', modelId: 'openai/gpt-oss-120b', displayName: 'GPT-OSS 120B', sizeLabel: 'Frontier', intelligenceRank: 6, speedRank: 2, monthlyTokenBudget: '~6M', supportsVision: false, rpmLimit: 30, rpdLimit: 1000, enabled: true, priority: 2, reliability: 0.9, speed: 0.98, intelligence: 0.72, headroom: 1, rateLimit: 0.7, totalRequests: 833 },
+ { modelDbId: 3, platform: 'cerebras', modelId: 'llama-3.3-70b', displayName: 'Llama 3.3 70B', sizeLabel: 'Large', intelligenceRank: 4, speedRank: 1, monthlyTokenBudget: '~50M', supportsVision: false, rpmLimit: 30, rpdLimit: 14400, enabled: true, priority: 3, reliability: 0.88, speed: 1.0, intelligence: 0.5, headroom: 1, rateLimit: 1, totalRequests: 256 },
+ { modelDbId: 4, platform: 'google', modelId: 'gemini-2.5-flash', displayName: 'Gemini 2.5 Flash', sizeLabel: 'Large', intelligenceRank: 4, speedRank: 5, monthlyTokenBudget: '~3M', supportsVision: true, rpmLimit: 10, rpdLimit: 20, enabled: true, priority: 4, reliability: 0.97, speed: 0.78, intelligence: 0.52, headroom: 0.45, rateLimit: 1, totalRequests: 90 },
+ { modelDbId: 5, platform: 'nvidia', modelId: 'llama-4-scout', displayName: 'Llama 4 Scout', sizeLabel: 'Medium', intelligenceRank: 7, speedRank: 4, monthlyTokenBudget: '~30M', supportsVision: true, rpmLimit: 40, rpdLimit: null, enabled: true, priority: 5, reliability: 0.7, speed: 0.83, intelligence: 0.33, headroom: 1, rateLimit: 1, totalRequests: 47 },
+ { modelDbId: 6, platform: 'openrouter', modelId: 'deepseek/deepseek-v3.1:free', displayName: 'DeepSeek V3.1', sizeLabel: 'Frontier', intelligenceRank: 2, speedRank: 10, monthlyTokenBudget: '~6M', supportsVision: false, rpmLimit: 20, rpdLimit: 200, enabled: false, priority: 6, reliability: 0.5, speed: 0.4, intelligence: 0.67, headroom: 1, rateLimit: 1, totalRequests: 0 },
+ { modelDbId: 7, platform: 'mistral', modelId: 'mistral-large', displayName: 'Mistral Large', sizeLabel: 'Large', intelligenceRank: 5, speedRank: 6, monthlyTokenBudget: '~15M', supportsVision: false, rpmLimit: 60, rpdLimit: 500, enabled: true, priority: 7, reliability: 0.82, speed: 0.6, intelligence: 0.45, headroom: 1, rateLimit: 1, totalRequests: 178 },
+]
+
+function budgetTokens(label: string): number {
+ const m = label.match(/~?([\d.]+)(?:-([\d.]+))?([MK])?/)
+ if (!m) return 0
+ const n = parseFloat(m[2] ?? m[1])
+ const unit = m[3] === 'M' ? 1_000_000 : m[3] === 'K' ? 1_000 : 1
+ return n * unit
+}
+
+function score(m: MockModel): number {
+ const w = activeWeights()
+ const base = w.reliability * m.reliability + w.speed * m.speed + w.intelligence * m.intelligence
+ return base * m.headroom * m.rateLimit
+}
+
+function readBody(req: any): Promise<any> {
+ return new Promise(resolve => {
+ let data = ''
+ req.on('data', (c: any) => { data += c })
+ req.on('end', () => { try { resolve(JSON.parse(data || '{}')) } catch { resolve({}) } })
+ })
+}
+
+export function mockApiPlugin(): Plugin {
+ return {
+ name: 'freellmapi-dev-mock',
+ configureServer(server) {
+ server.middlewares.use(async (req: any, res: any, next: any) => {
+ const url = (req.url || '').split('?')[0]
+ if (!url.startsWith('/api/')) return next()
+ const send = (obj: any, status = 200) => {
+ res.statusCode = status
+ res.setHeader('Content-Type', 'application/json')
+ res.end(JSON.stringify(obj))
+ }
+
+ // Auth gate — always "logged in" in mock mode.
+ if (url === '/api/auth/status') return send({ needsSetup: false, authenticated: true, email: 'dev@local' })
+ if (url === '/api/ping') return send({ status: 'ok', timestamp: new Date().toISOString() })
+
+ if (url === '/api/fallback' && req.method === 'GET') {
+ const rows = [...models].sort((a, b) => a.priority - b.priority).map(m => ({
+ modelDbId: m.modelDbId, priority: m.priority, effectivePriority: m.priority,
+ penalty: m.rateLimit < 1 ? Math.round((1 - m.rateLimit) * 10) : 0,
+ rateLimitHits: m.rateLimit < 1 ? 3 : 0,
+ enabled: m.enabled, platform: m.platform, modelId: m.modelId, displayName: m.displayName,
+ intelligenceRank: m.intelligenceRank, speedRank: m.speedRank, sizeLabel: m.sizeLabel,
+ rpmLimit: m.rpmLimit, rpdLimit: m.rpdLimit, monthlyTokenBudget: m.monthlyTokenBudget,
+ supportsVision: m.supportsVision, keyCount: 3,
+ }))
+ return send(rows)
+ }
+
+ if (url === '/api/fallback' && req.method === 'PUT') {
+ const body = await readBody(req)
+ for (const e of body as any[]) {
+ const m = models.find(x => x.modelDbId === e.modelDbId)
+ if (m) { m.priority = e.priority; m.enabled = e.enabled }
+ }
+ return send({ success: true })
+ }
+
+ if (url === '/api/fallback/routing' && req.method === 'GET') {
+ const scores = [...models]
+ .map(m => ({
+ modelDbId: m.modelDbId, platform: m.platform, modelId: m.modelId, displayName: m.displayName,
+ enabled: m.enabled, reliability: m.reliability, speed: m.speed, intelligence: m.intelligence,
+ headroom: m.headroom, rateLimit: m.rateLimit, score: score(m), totalRequests: m.totalRequests,
+ }))
+ .sort((a, b) => b.score - a.score)
+ return send({ strategy, weights: strategy === 'priority' ? null : activeWeights(), customWeights, scores })
+ }
+
+ if (url === '/api/fallback/routing' && req.method === 'PUT') {
+ const body = await readBody(req)
+ if (typeof body.strategy === 'string') strategy = body.strategy
+ if (body.weights && typeof body.weights === 'object') {
+ const { reliability = 0, speed = 0, intelligence = 0 } = body.weights
+ const sum = reliability + speed + intelligence
+ if (sum > 0) {
+ customWeights = { reliability: reliability / sum, speed: speed / sum, intelligence: intelligence / sum }
+ }
+ }
+ return send({ strategy, presets: PRESETS, customWeights })
+ }
+
+ if (url === '/api/fallback/token-usage') {
+ const withKeys = models
+ const modelBudgets = withKeys.map(m => ({ displayName: m.displayName, platform: m.platform, budget: budgetTokens(m.monthlyTokenBudget) }))
+ const totalBudget = modelBudgets.reduce((s, m) => s + m.budget, 0)
+ return send({ totalBudget, totalUsed: Math.round(totalBudget * 0.18), models: modelBudgets })
+ }
+
+ // Anything else under /api → empty 200 so pages don't hard-crash.
+ return send({})
+ })
+ },
+ }
+}
diff --git a/client/src/App.tsx b/client/src/App.tsx
index ddf54e5f..b2b08bc0 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -18,6 +18,7 @@ import PlaygroundPage from '@/pages/PlaygroundPage'
import FallbackPage from '@/pages/FallbackPage'
import EmbeddingsPage from '@/pages/EmbeddingsPage'
import AnalyticsPage from '@/pages/AnalyticsPage'
+import PremiumPage from '@/pages/PremiumPage'
const queryClient = new QueryClient()
@@ -26,6 +27,7 @@ const navItems = [
{ to: '/playground', label: 'Playground' },
{ to: '/keys', label: 'Keys' },
{ to: '/analytics', label: 'Analytics' },
+ { to: '/premium', label: 'Premium' },
]
function getPreferredDarkMode() {
@@ -204,6 +206,7 @@ function App() {
<Route path="/keys" element={<KeysPage />} />
<Route path="/fallback" element={<Navigate to="/models/chat" replace />} />
<Route path="/analytics" element={<AnalyticsPage />} />
+ <Route path="/premium" element={<PremiumPage />} />
<Route path="/test" element={<Navigate to="/playground" replace />} />
<Route path="/health" element={<Navigate to="/keys" replace />} />
</Routes>
diff --git a/client/src/pages/PremiumPage.tsx b/client/src/pages/PremiumPage.tsx
new file mode 100644
index 00000000..0b08c280
--- /dev/null
+++ b/client/src/pages/PremiumPage.tsx
@@ -0,0 +1,264 @@
+import { useState } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { ExternalLink, RefreshCw, Sparkles } from 'lucide-react'
+import { apiFetch } from '@/lib/api'
+import { PageHeader } from '@/components/page-header'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { Badge } from '@/components/ui/badge'
+
+interface LicenseStatus {
+ valid: boolean
+ plan: 'annual' | 'lifetime' | null
+ status: string | null
+ expiresAt: string | null
+ cancelAtPeriodEnd?: boolean
+ reason?: string
+ checkedAtMs: number
+}
+
+interface CatalogSyncState {
+ baseUrl: string
+ appliedVersion: string | null
+ appliedTier: string | null
+ lastSyncMs: number | null
+ lastError: string | null
+}
+
+interface PremiumStatus {
+ hasKey: boolean
+ maskedKey: string | null
+ license: LicenseStatus | null
+ catalog: CatalogSyncState
+ siteUrl: string
+}
+
+const PLAN_LABEL: Record<string, string> = {
+ annual: 'Premium Annual',
+ lifetime: 'Premium Lifetime',
+}
+
+function fmtWhen(ms: number | null): string {
+ if (!ms) return 'never'
+ return new Date(ms).toLocaleString()
+}
+
+function fmtDate(iso: string | null): string {
+ if (!iso) return ''
+ return new Date(iso).toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })
+}
+
+export default function PremiumPage() {
+ const queryClient = useQueryClient()
+ const [keyInput, setKeyInput] = useState('')
+
+ const { data, isLoading } = useQuery<PremiumStatus>({
+ queryKey: ['premium'],
+ queryFn: () => apiFetch('/api/premium'),
+ })
+
+ const invalidate = () => {
+ queryClient.invalidateQueries({ queryKey: ['premium'] })
+ // A sync may have changed the model list and quirks.
+ queryClient.invalidateQueries({ queryKey: ['models'] })
+ }
+
+ const activate = useMutation({
+ mutationFn: (key: string) =>
+ apiFetch('/api/premium/key', { method: 'POST', body: JSON.stringify({ key }) }),
+ onSuccess: () => {
+ setKeyInput('')
+ invalidate()
+ },
+ })
+
+ const removeKey = useMutation({
+ mutationFn: () => apiFetch('/api/premium/key', { method: 'DELETE' }),
+ onSuccess: invalidate,
+ })
+
+ const syncNow = useMutation({
+ mutationFn: () => apiFetch('/api/premium/sync', { method: 'POST' }),
+ onSuccess: invalidate,
+ })
+
+ const openPortal = useMutation({
+ mutationFn: () => apiFetch<{ url: string }>('/api/premium/portal', { method: 'POST' }),
+ onSuccess: ({ url }) => {
+ window.open(url, '_blank', 'noopener')
+ },
+ })
+
+ if (isLoading || !data) {
+ return (
+ <div>
+ <PageHeader title="Premium" description="The live model catalog, on every device." />
+ <p className="text-sm text-muted-foreground">Loading…</p>
+ </div>
+ )
+ }
+
+ const { hasKey, maskedKey, license, catalog, siteUrl } = data
+ const live = catalog.appliedTier === 'live'
+ const licensed = hasKey && license?.valid
+
+ return (
+ <div>
+ <PageHeader
+ title="Premium"
+ description="The live model catalog, on every device."
+ actions={
+ <Button variant="outline" size="sm" onClick={() => syncNow.mutate()} disabled={syncNow.isPending}>
+ <RefreshCw className={syncNow.isPending ? 'animate-spin' : ''} />
+ {syncNow.isPending ? 'Syncing…' : 'Check for updates'}
+ </Button>
+ }
+ />
+
+ <div className="space-y-8">
+ {/* Catalog feed state */}
+ <section>
+ <h2 className="text-sm font-medium mb-3">Catalog feed</h2>
+ <div className="rounded-3xl border bg-card p-5">
+ <div className="flex flex-wrap items-center gap-x-6 gap-y-3">
+ <div className="flex items-center gap-2">
+ <span className={`inline-block size-2 rounded-full ${live ? 'bg-emerald-500' : 'bg-muted-foreground/40'}`} />
+ <span className="text-sm font-medium">{live ? 'Live feed' : 'Monthly snapshot'}</span>
+ <Badge variant="outline" className="font-mono text-[11px]">
+ {catalog.appliedVersion ?? 'bundled'}
+ </Badge>
+ </div>
+ <span className="text-xs text-muted-foreground">Last checked: {fmtWhen(catalog.lastSyncMs)}</span>
+ </div>
+ <p className="text-xs text-muted-foreground mt-3">
+ {live
+ ? 'New free models, quota changes, and quirk fixes land here within hours of being shipped. The app checks automatically twice a day; nothing to do.'
+ : 'Free tier: the catalog refreshes from a monthly snapshot, checked automatically twice a day. Premium switches this to the live feed, updated every 2-3 days.'}
+ </p>
+ {catalog.lastError && (
+ <p className="text-destructive text-xs mt-2">Last sync problem: {catalog.lastError}</p>
+ )}
+ </div>
+ </section>
+
+ {/* License */}
+ <section>
+ <h2 className="text-sm font-medium mb-3">License</h2>
+ {hasKey ? (
+ <div className="rounded-3xl border bg-card p-5 space-y-4">
+ <div className="flex flex-wrap items-center gap-3">
+ <span className="font-mono text-sm">{maskedKey}</span>
+ {licensed ? (
+ <Badge className="bg-emerald-500/15 text-emerald-600 dark:text-emerald-400 border-transparent">
+ {PLAN_LABEL[license?.plan ?? ''] ?? 'Premium'}
+ </Badge>
+ ) : (
+ <Badge variant="outline" className="text-destructive border-destructive/40">
+ {license?.reason === 'expired' ? 'Expired' : 'Inactive'}
+ </Badge>
+ )}
+ </div>
+
+ <p className="text-xs text-muted-foreground">
+ {licensed && license?.plan === 'lifetime' && 'Lifetime license: never expires.'}
+ {licensed && license?.plan === 'annual' && !license.cancelAtPeriodEnd && license.expiresAt &&
+ `Renews on ${fmtDate(license.expiresAt)}.`}
+ {licensed && license?.plan === 'annual' && license.cancelAtPeriodEnd && license.expiresAt &&
+ `Will not renew. Premium until ${fmtDate(license.expiresAt)}, then this install falls back to the free monthly catalog.`}
+ {!licensed &&
+ 'This key is no longer active. The app keeps working on the free monthly catalog.'}
+ </p>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button variant="outline" size="sm" onClick={() => openPortal.mutate()} disabled={openPortal.isPending}>
+ <ExternalLink />
+ {openPortal.isPending ? 'Opening…' : 'Manage subscription'}
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => removeKey.mutate()}
+ disabled={removeKey.isPending}
+ className="text-muted-foreground"
+ >
+ Remove key from this device
+ </Button>
+ </div>
+ <p className="text-[11px] text-muted-foreground">
+ Manage subscription opens Stripe&apos;s billing portal: cancel, update your card, or download
+ invoices. Removing the key only deactivates this device; your purchase is untouched.
+ </p>
+ {openPortal.isError && (
+ <p className="text-destructive text-xs">{(openPortal.error as Error).message}</p>
+ )}
+ </div>
+ ) : (
+ <div className="rounded-3xl border bg-card p-5 space-y-4">
+ <form
+ className="flex flex-wrap items-end gap-3"
+ onSubmit={(e) => {
+ e.preventDefault()
+ if (keyInput.trim()) activate.mutate(keyInput.trim())
+ }}
+ >
+ <div className="space-y-1.5 flex-1 min-w-[260px]">
+ <Label className="text-xs">License key</Label>
+ <Input
+ value={keyInput}
+ onChange={(e) => setKeyInput(e.target.value)}
+ placeholder="fla_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+ className="font-mono text-xs"
+ autoComplete="off"
+ />
+ </div>
+ <Button type="submit" size="sm" disabled={!keyInput.trim() || activate.isPending}>
+ {activate.isPending ? 'Activating…' : 'Activate'}
+ </Button>
+ </form>
+ {activate.isError && (
+ <p className="text-destructive text-xs">{(activate.error as Error).message}</p>
+ )}
+ <p className="text-xs text-muted-foreground">
+ Your key is in your purchase email and on the post-checkout page. Lost it?{' '}
+ <a className="underline hover:text-foreground" href={`${siteUrl}/manage.html`} target="_blank" rel="noopener noreferrer">
+ Recover it on the website
+ </a>
+ .
+ </p>
+ </div>
+ )}
+ </section>
+
+ {/* Upsell, only when not licensed */}
+ {!licensed && (
+ <section>
+ <div className="rounded-3xl border bg-card p-5 flex flex-wrap items-center justify-between gap-4">
+ <div className="flex items-start gap-3">
+ <Sparkles className="size-4 mt-0.5 text-muted-foreground" />
+ <div>
+ <p className="text-sm font-medium">Go live for $19 a year</p>
+ <p className="text-xs text-muted-foreground mt-0.5">
+ New free models the moment they exist, instead of on the 1st of the month. One key, every
+ device. Cancel anytime; the router stays free forever.
+ </p>
+ </div>
+ </div>
+ <a
+ href={`${siteUrl}/#pricing`}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="shrink-0"
+ >
+ <Button size="sm">
+ Go Premium
+ <ExternalLink />
+ </Button>
+ </a>
+ </div>
+ </section>
+ )}
+ </div>
+ </div>
+ )
+}
diff --git a/desktop/src/server-host.ts b/desktop/src/server-host.ts
index af3322ed..7497f58d 100644
--- a/desktop/src/server-host.ts
+++ b/desktop/src/server-host.ts
@@ -12,6 +12,7 @@ import type { Server } from 'node:http';
import { createApp } from '../../server/src/app.js';
import { initDb, getDb, getUnifiedApiKey } from '../../server/src/db/index.js';
import { startHealthChecker } from '../../server/src/services/health.js';
+import { startCatalogSync } from '../../server/src/services/catalog-sync.js';
import { userCount, createUser, createSession } from '../../server/src/services/auth.js';
export { getDb, getUnifiedApiKey };
@@ -34,6 +35,7 @@ export async function startServer(opts: StartOptions): Promise<ServerHandle> {
const app = createApp();
const { server, port } = await listenWithScan(app, opts.host, opts.preferredPort);
startHealthChecker();
+ startCatalogSync();
return { server, port };
}
diff --git a/docs/index.html b/docs/index.html
index 0d047f68..d4821f0d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -2,455 +2,13 @@
<html lang="en">
<head>
<meta charset="UTF-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>FreeLLMAPI — One key. 1.7 billion free LLM tokens. Every month.</title>
-<meta name="description" content="A self-hosted, OpenAI-compatible proxy that routes across 16 free-tier LLM providers — Gemini, OpenRouter, Cerebras, Groq, Mistral, GitHub Models, OpenCode Zen, Cohere, Cloudflare, Z.ai, NVIDIA, HuggingFace, Ollama, Kilo, Pollinations, LLM7 — plus any custom OpenAI-compatible endpoint. ~1.7B free tokens / month, 100+ models." />
-<meta name="theme-color" content="#0a0a0a" />
-<link rel="canonical" href="https://tashfeenahmed.github.io/freellmapi/" />
-
-<!-- Open Graph -->
-<meta property="og:type" content="website" />
-<meta property="og:site_name" content="FreeLLMAPI" />
-<meta property="og:title" content="FreeLLMAPI — 1.7B free LLM tokens / month" />
-<meta property="og:description" content="One self-hosted, OpenAI-compatible proxy across 16 free-tier LLM providers. 100+ models. ~1.7B free tokens per month." />
-<meta property="og:url" content="https://tashfeenahmed.github.io/freellmapi/" />
-<meta property="og:image" content="https://tashfeenahmed.github.io/freellmapi/og.png" />
-<meta property="og:image:width" content="1200" />
-<meta property="og:image:height" content="630" />
-<meta property="og:image:alt" content="FreeLLMAPI — 1.7B free tokens / month, across 16 providers and 100+ models." />
-
-<!-- Twitter -->
-<meta name="twitter:card" content="summary_large_image" />
-<meta name="twitter:title" content="FreeLLMAPI — 1.7B free LLM tokens / month" />
-<meta name="twitter:description" content="One self-hosted, OpenAI-compatible proxy across 16 free-tier LLM providers. 100+ models. ~1.7B free tokens per month." />
-<meta name="twitter:image" content="https://tashfeenahmed.github.io/freellmapi/og.png" />
-<link rel="icon" href="data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='9' fill='%230a0a0a'/%3E%3Ccircle cx='16' cy='16' r='9' fill='%23ffffff'/%3E%3Ccircle cx='16' cy='16' r='3.2' fill='%230a0a0a'/%3E%3C/svg%3E" />
-<style>
- :root {
- --bg: #fafafa;
- --fg: #0a0a0a;
- --muted: #6b6b6b;
- --border: #e5e5e5;
- --card: #ffffff;
- --accent: #0a0a0a;
- --accent-soft: #f0f0f0;
- --shadow: 0 1px 2px rgba(0, 0, 0, 0.04), 0 8px 24px rgba(0, 0, 0, 0.05);
- --shadow-lg: 0 4px 12px rgba(0, 0, 0, 0.08), 0 24px 56px rgba(0, 0, 0, 0.10);
- --radius-sm: 12px;
- --radius: 20px;
- --radius-lg: 28px;
- }
- * { box-sizing: border-box; }
- html { scroll-behavior: smooth; }
- body {
- margin: 0;
- background: var(--bg);
- color: var(--fg);
- font-family: -apple-system, BlinkMacSystemFont, 'Inter', system-ui, sans-serif;
- line-height: 1.6;
- -webkit-font-smoothing: antialiased;
- }
- .mono { font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, 'Cascadia Code', monospace; }
- .container { max-width: 1100px; margin: 0 auto; padding: 0 24px; }
- nav {
- display: flex; align-items: center; justify-content: space-between;
- padding: 20px 0; gap: 16px;
- }
- .brand {
- display: inline-flex; align-items: center; gap: 10px;
- font-weight: 700; font-size: 17px; color: var(--fg); text-decoration: none;
- }
- .brand-mark {
- width: 32px; height: 32px; border-radius: 9px;
- background: var(--fg);
- display: grid; place-items: center;
- box-shadow: var(--shadow);
- }
- .brand-mark svg { width: 18px; height: 18px; display: block; }
- .nav-links { display: flex; gap: 8px; }
- .nav-links a {
- color: var(--muted); text-decoration: none; font-size: 14px;
- padding: 8px 14px; border-radius: 999px; transition: all 0.15s;
- }
- .nav-links a:hover { background: var(--accent-soft); color: var(--fg); }
-
- .hero { padding: 80px 0 48px; text-align: center; }
- .badge {
- display: inline-flex; align-items: center; gap: 8px;
- padding: 6px 14px; border-radius: 999px;
- background: var(--card); color: var(--fg);
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: 12px; font-weight: 500; letter-spacing: 0.05em;
- border: 1px solid var(--border);
- }
- .badge-dot {
- width: 6px; height: 6px; border-radius: 50%; background: var(--fg);
- box-shadow: 0 0 0 4px rgba(10, 10, 10, 0.10);
- animation: pulse 2s ease-in-out infinite;
- }
- @keyframes pulse { 50% { box-shadow: 0 0 0 8px transparent; } }
- h1 {
- font-size: clamp(36px, 6vw, 64px);
- line-height: 1.05; letter-spacing: -0.03em;
- margin: 24px 0 20px; font-weight: 800;
- }
- h1 .gradient {
- color: var(--muted);
- }
- .subtitle {
- font-size: clamp(17px, 2vw, 20px); color: var(--muted);
- max-width: 640px; margin: 0 auto 40px;
- }
- .cta-row { display: inline-flex; flex-wrap: wrap; gap: 12px; justify-content: center; }
- .btn {
- display: inline-flex; align-items: center; gap: 8px;
- padding: 14px 24px; border-radius: 999px;
- font-size: 15px; font-weight: 600; text-decoration: none;
- transition: all 0.2s; border: 1px solid transparent;
- }
- .btn-primary {
- background: var(--fg); color: var(--bg);
- }
- .btn-primary:hover { transform: translateY(-1px); box-shadow: var(--shadow-lg); }
- .btn-secondary {
- background: var(--card); color: var(--fg); border-color: var(--border);
- }
- .btn-secondary:hover { background: var(--accent-soft); border-color: var(--fg); }
-
- /* Tokens stat block — the centerpiece */
- .tokens-stat {
- margin: 64px auto; max-width: 760px;
- background: var(--fg); color: var(--bg);
- border-radius: var(--radius-lg);
- padding: 64px 32px; text-align: center;
- box-shadow: var(--shadow-lg);
- }
- .tokens-label {
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: 12px; text-transform: uppercase; letter-spacing: 0.25em; opacity: 0.6;
- }
- .tokens-number {
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: clamp(72px, 14vw, 160px); font-weight: 700;
- line-height: 1; margin: 22px 0 14px; letter-spacing: -0.05em;
- font-variant-numeric: tabular-nums;
- display: block;
- }
- .tokens-unit {
- display: block;
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: clamp(13px, 1.4vw, 15px); font-weight: 500;
- text-transform: uppercase; letter-spacing: 0.4em; opacity: 0.6;
- margin-top: 4px;
- }
- .tokens-sub { margin-top: 28px; opacity: 0.7; font-size: 14px; max-width: 520px; margin-left: auto; margin-right: auto; }
-
- /* Sections */
- section { padding: 56px 0; }
- .section-header { text-align: center; margin-bottom: 40px; }
- .section-eyebrow {
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- color: var(--muted); font-size: 12px; font-weight: 500;
- text-transform: uppercase; letter-spacing: 0.25em;
- }
- h2 {
- font-size: clamp(28px, 4vw, 40px); margin: 8px 0 12px;
- font-weight: 700; letter-spacing: -0.02em;
- }
- .section-sub { color: var(--muted); max-width: 600px; margin: 0 auto; }
-
- /* Provider grid */
- .provider-grid {
- display: grid; gap: 16px;
- grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
- }
- .provider-card {
- background: var(--card);
- border-radius: var(--radius);
- padding: 24px;
- border: 1px solid var(--border);
- box-shadow: var(--shadow);
- transition: all 0.2s ease;
- }
- .provider-card:hover {
- transform: translateY(-2px);
- box-shadow: var(--shadow-lg);
- border-color: var(--fg);
- }
- .provider-name {
- font-weight: 700; font-size: 16px; margin: 0 0 6px;
- display: flex; align-items: center; gap: 8px;
- }
- .provider-icon {
- width: 36px; height: 36px; border-radius: 10px; flex: none;
- background: var(--accent-soft); border: 1px solid var(--border);
- display: grid; place-items: center;
- }
- .provider-icon img {
- width: 60%; height: 60%; display: block;
- filter: grayscale(100%) contrast(1.1);
- }
- /* Logos that ship their own brand background (e.g. Z.ai's dark rounded square) */
- .provider-icon.bleed { background: none; border: none; padding: 0; }
- .provider-icon.bleed img { width: 100%; height: 100%; border-radius: 10px; }
- .provider-tokens {
- display: inline-flex; align-items: baseline; gap: 4px;
- margin: 14px 0 8px;
- }
- .provider-tokens .num {
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: 26px; font-weight: 700; letter-spacing: -0.03em;
- color: var(--fg); font-variant-numeric: tabular-nums;
- }
- .provider-tokens .unit { font-size: 13px; color: var(--muted); font-weight: 500; }
- .provider-tokens .label { color: var(--muted); font-size: 12px; margin-left: auto; }
- .provider-models { color: var(--muted); font-size: 13px; line-height: 1.5; }
- .provider-models b { color: var(--fg); font-weight: 600; }
-
- /* How it works */
- .steps {
- display: grid; gap: 16px;
- grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
- }
- .step {
- background: var(--card); border-radius: var(--radius);
- padding: 28px; border: 1px solid var(--border); box-shadow: var(--shadow);
- }
- .step-num {
- display: inline-grid; place-items: center;
- width: 36px; height: 36px; border-radius: 12px;
- background: var(--fg); color: var(--bg);
- font-weight: 800; margin-bottom: 14px;
- }
- .step h3 { margin: 0 0 6px; font-size: 17px; font-weight: 700; }
- .step p { margin: 0; color: var(--muted); font-size: 14px; }
-
- /* Code block — terminal aesthetic */
- .terminal {
- max-width: 760px; margin: 0 auto;
- background: var(--fg); color: #d4d4d4;
- border-radius: var(--radius);
- overflow: hidden; box-shadow: var(--shadow-lg);
- border: 1px solid var(--fg);
- }
- .terminal-chrome {
- display: flex; align-items: center; gap: 8px;
- padding: 14px 18px;
- background: rgba(255,255,255,0.04);
- border-bottom: 1px solid rgba(255,255,255,0.08);
- }
- .terminal-chrome .dot {
- width: 12px; height: 12px; border-radius: 50%;
- background: rgba(255,255,255,0.15);
- }
- .terminal-chrome .filename {
- margin-left: 12px; color: rgba(255,255,255,0.55);
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, monospace;
- font-size: 12px; letter-spacing: 0.05em;
- }
- .terminal-body {
- padding: 24px 28px;
- font-family: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Monaco, monospace;
- font-size: 13.5px; line-height: 1.85;
- overflow-x: auto;
- margin: 0;
- }
- .terminal-body .prompt { color: #8fa9ff; user-select: none; margin-right: 10px; }
- .terminal-body .c { color: rgba(255,255,255,0.4); font-style: italic; }
- .terminal-body .k { color: #ffffff; font-weight: 600; }
- .terminal-body .s { color: #c0c0c0; }
- .terminal-body .blank { display: block; height: 0.4em; }
-
- /* Footer */
- footer {
- margin-top: 64px; padding: 40px 0;
- border-top: 1px solid var(--border);
- color: var(--muted); font-size: 13px;
- text-align: center;
- }
- footer a { color: var(--fg); text-decoration: underline; text-underline-offset: 3px; }
- footer a:hover { text-decoration: underline; }
-</style>
+<title>FreeLLMAPI has moved to freellmapi.co</title>
+<meta name="robots" content="noindex" />
+<link rel="canonical" href="https://freellmapi.co/" />
+<meta http-equiv="refresh" content="0; url=https://freellmapi.co/" />
</head>
<body>
- <div class="container">
- <nav>
- <a class="brand" href="#">
- <span class="brand-mark">
- <svg viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
- <circle cx="16" cy="16" r="11" fill="#ffffff"/>
- <circle cx="16" cy="16" r="4" fill="#0a0a0a"/>
- </svg>
- </span>
- <span>FreeLLMAPI</span>
- </a>
- <div class="nav-links">
- <a href="#providers">Providers</a>
- <a href="#start">Quick start</a>
- <a href="https://github.com/tashfeenahmed/freellmapi" target="_blank" rel="noopener">GitHub</a>
- </div>
- </nav>
-
- <header class="hero">
- <span class="badge"><span class="badge-dot"></span> 100+ free models · 16 providers · self-hosted</span>
- <h1>One key.<br><span class="gradient">1.7 billion</span> free tokens.<br>Every month.</h1>
- <p class="subtitle">A self-hosted, OpenAI-compatible proxy that routes across every credible free-tier LLM provider. Bring your own keys; we just point requests at whichever provider still has budget left.</p>
- <div class="cta-row">
- <a class="btn btn-primary" href="https://github.com/tashfeenahmed/freellmapi" target="_blank" rel="noopener">View on GitHub →</a>
- <a class="btn btn-secondary" href="#start">Quick start</a>
- </div>
- </header>
-
- <div class="tokens-stat">
- <div class="tokens-label">Aggregate monthly free budget</div>
- <div class="tokens-number">1.7B</div>
- <div class="tokens-unit">tokens · per month</div>
- <div class="tokens-sub">Across 100+ free-tier models on 16 providers, plus any custom OpenAI-compatible endpoint. Mistral alone contributes ~1B; everything else is bonus.</div>
- </div>
-
- <section id="providers">
- <div class="section-header">
- <div class="section-eyebrow">The catalog</div>
- <h2>Every free tier worth using</h2>
- <p class="section-sub">Only providers with <strong>recurring</strong> free quotas, no credit card required, and a self-serve API.</p>
- </div>
- <div class="provider-grid">
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/google.svg" alt="" /></span>Google Gemini</div>
- <div class="provider-tokens"><span class="num">~3M</span><span class="unit">/mo</span><span class="label">per model</span></div>
- <div class="provider-models">Gemini 2.5 Flash · Flash-Lite · 3.1 Pro/Flash previews. <b>20 RPD per model</b>.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/openrouter.svg" alt="" /></span>OpenRouter</div>
- <div class="provider-tokens"><span class="num">~6M</span><span class="unit">/mo</span><span class="label">per model</span></div>
- <div class="provider-models">19 <code>:free</code> models — DeepSeek, Kimi, Qwen, Llama, Gemma, Nemotron, Tencent HY3 …</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/cerebras.svg" alt="" /></span>Cerebras</div>
- <div class="provider-tokens"><span class="num">~30M</span><span class="unit">/mo</span><span class="label">shared</span></div>
- <div class="provider-models">Qwen3 235B · GPT-OSS 120B · Llama 3.1 8B. <b>1M TPD · 30 RPM</b>. Fastest tokens you'll ever see.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/groq.svg" alt="" /></span>Groq</div>
- <div class="provider-tokens"><span class="num">~30M</span><span class="unit">/mo</span><span class="label">per model</span></div>
- <div class="provider-models">Llama 3.3 70B · Llama 4 Scout · GPT-OSS 120B/20B · Qwen3 32B. <b>1000 RPD</b>.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/mistral.svg" alt="" /></span>Mistral La Plateforme</div>
- <div class="provider-tokens"><span class="num">~1B</span><span class="unit">/mo</span><span class="label">shared</span></div>
- <div class="provider-models">Mistral Large/Medium · Codestral · Devstral · Magistral. The biggest free pool of any provider.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/github.svg" alt="" /></span>GitHub Models</div>
- <div class="provider-tokens"><span class="num">~18M</span><span class="unit">/mo</span><span class="label">est.</span></div>
- <div class="provider-models">GPT-4.1 · GPT-4o. <b>50 RPD</b> on the free Copilot tier. Higher caps with paid Copilot.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:12px;font-weight:700;color:var(--muted)">OC</span>OpenCode Zen</div>
- <div class="provider-tokens"><span class="num">promo</span><span class="label">rotating free models</span></div>
- <div class="provider-models">DeepSeek V4 Flash · Nemotron 3 Ultra · MiniMax M3 · MiMo V2.5 · Big Pickle. Free account key.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/cloudflare.svg" alt="" /></span>Cloudflare Workers AI</div>
- <div class="provider-tokens"><span class="num">~20M</span><span class="unit">/mo</span><span class="label">shared</span></div>
- <div class="provider-models">Kimi K2.5/K2.6 · Qwen3 30B · GLM-4.7 Flash · Llama 4 Scout · IBM Granite 4.0. <b>10K Neurons/day</b>.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/zai.svg" alt="" /></span>Z.ai (Zhipu)</div>
- <div class="provider-tokens"><span class="num">~30M</span><span class="unit">/mo</span><span class="label">shared</span></div>
- <div class="provider-models">GLM-4.5 Flash · GLM-4.7 Flash. Both <code>:free</code> — perpetually, no card.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/cohere.svg" alt="" /></span>Cohere</div>
- <div class="provider-tokens"><span class="num">~1-2M</span><span class="unit">/mo</span><span class="label">shared</span></div>
- <div class="provider-models">Command R+. Trial key: <b>1000 calls/month</b>, 20 RPM.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon"><img src="logos/nvidia.svg" alt="" /></span>NVIDIA NIM</div>
- <div class="provider-tokens"><span class="num">credits</span><span class="unit"></span><span class="label">disabled</span></div>
- <div class="provider-models">Llama 3.1 70B. Disabled by default — credit-based, not recurring.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:12px;font-weight:700;color:var(--muted)">HF</span>HuggingFace</div>
- <div class="provider-tokens"><span class="num">~3M</span><span class="unit">/mo</span><span class="label">router credit</span></div>
- <div class="provider-models">Inference Providers router → DeepSeek V4 · Kimi K2.6 · Qwen3. Recurring router credit, no card.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:12px;font-weight:700;color:var(--muted)">OL</span>Ollama Cloud</div>
- <div class="provider-tokens"><span class="num">free</span><span class="unit"></span><span class="label">GPU-time</span></div>
- <div class="provider-models">GLM-4.7 · Kimi K2 · gpt-oss · Qwen3. Free plan: 1 concurrent model, session/GPU-time caps.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:14px;font-weight:700;color:var(--muted)">K</span>Kilo Gateway</div>
- <div class="provider-tokens"><span class="num">anon</span><span class="unit"></span><span class="label">~200/hr</span></div>
- <div class="provider-models"><code>:free</code> routes — anonymous access works per-IP; a key raises the limit.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:14px;font-weight:700;color:var(--muted)">P</span>Pollinations</div>
- <div class="provider-tokens"><span class="num">anon</span><span class="unit"></span><span class="label">free tier</span></div>
- <div class="provider-models">GPT-OSS 20B (<code>openai-fast</code>), tools supported. Anonymous tier, no key.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:12px;font-weight:700;color:var(--muted)">L7</span>LLM7</div>
- <div class="provider-tokens"><span class="num">anon</span><span class="unit"></span><span class="label">~100/hr</span></div>
- <div class="provider-models">GPT-OSS · Llama 3.1 Turbo · Codestral · GLM via one token. Anonymous access works.</div>
- </div>
- <div class="provider-card">
- <div class="provider-name"><span class="provider-icon" style="font-size:18px;font-weight:700;color:var(--muted)">+</span>Custom endpoint</div>
- <div class="provider-tokens"><span class="num">∞</span><span class="unit"></span><span class="label">your server</span></div>
- <div class="provider-models">Point at any OpenAI-compatible URL — llama.cpp, LM Studio, vLLM, a local Ollama, or a remote gateway.</div>
- </div>
- </div>
- </section>
-
- <section id="start">
- <div class="section-header">
- <div class="section-eyebrow">Three minutes to first token</div>
- <h2>Quick start</h2>
- </div>
-
- <div class="steps" style="margin-bottom: 32px;">
- <div class="step">
- <div class="step-num">1</div>
- <h3>Install</h3>
- <p>One command with Docker. Or clone + <code>npm run dev</code> for development (Node 20+, dev UI on :5173).</p>
- </div>
- <div class="step">
- <div class="step-num">2</div>
- <h3>Drop in your keys</h3>
- <p>Sign up free at each provider, paste keys into the dashboard. No credit card needed for any of them.</p>
- </div>
- <div class="step">
- <div class="step-num">3</div>
- <h3>Point your SDK</h3>
- <p>Set <code>base_url</code> to your local proxy. Use any OpenAI-compatible client — Cursor, the SDK, curl, anything.</p>
- </div>
- </div>
-
- <div class="terminal">
- <div class="terminal-chrome">
- <span class="dot"></span><span class="dot"></span><span class="dot"></span>
- <span class="filename">~/freellmapi · zsh</span>
- </div>
- <pre class="terminal-body"><span class="c"># 1. one-line install (Docker; generates your encryption key, starts the container)</span>
-<span class="prompt">$</span><span class="k">curl</span> -fsSL https://tashfeenahmed.github.io/freellmapi/install.sh | bash
-<span class="blank"></span>
-<span class="c"># 2. open http://localhost:3001 — paste provider keys, copy your unified API key</span>
-<span class="blank"></span>
-<span class="c"># 3. call it like OpenAI</span>
-<span class="prompt">$</span><span class="k">curl</span> http://localhost:3001/v1/chat/completions \
- -H <span class="s">"Authorization: Bearer $FREELLMAPI_KEY"</span> \
- -H <span class="s">"Content-Type: application/json"</span> \
- -d <span class="s">'{"messages":[{"role":"user","content":"hi"}]}'</span>
-<span class="blank"></span>
-<span class="c"># developing instead? clone the repo, then: npm install &amp;&amp; npm run dev (UI on :5173)</span></pre>
- </div>
- </section>
-
- <footer>
- <p>FreeLLMAPI — open source, self-hosted, single-user. <a href="https://github.com/tashfeenahmed/freellmapi" target="_blank" rel="noopener">github.com/tashfeenahmed/freellmapi</a></p>
- <p style="margin-top: 6px; opacity: 0.7;">Built for personal use only. Each provider's ToS applies — don't expose this proxy publicly.</p>
- </footer>
- </div>
+ <p>FreeLLMAPI now lives at <a href="https://freellmapi.co/">freellmapi.co</a>. Redirecting&hellip;</p>
+ <script>location.replace('https://freellmapi.co/');</script>
</body>
</html>
diff --git a/docs/install.sh b/docs/install.sh
index e394a7fe..9c18a71d 100644
--- a/docs/install.sh
+++ b/docs/install.sh
@@ -1,149 +1,5 @@
#!/usr/bin/env bash
-#
-# FreeLLMAPI one-line installer (#250, idea by @StealthTensor).
-#
-# curl -fsSL https://tashfeenahmed.github.io/freellmapi/install.sh | bash
-#
-# What it does:
-# 1. Checks for Docker + Compose.
-# 2. Creates an install dir (default ~/freellmapi, override FREELLMAPI_DIR).
-# 3. Writes a docker-compose.yml pinned to ghcr.io/tashfeenahmed/freellmapi:latest
-# and a .env with a freshly generated ENCRYPTION_KEY (kept on re-runs).
-# 4. Pulls the image, starts the container, waits for the health endpoint.
-#
-# Options (env vars):
-# FREELLMAPI_DIR install directory (default: ~/freellmapi)
-# PORT host port for the dashboard (default: 3001)
-# HOST_BIND host interface to publish on (default: 127.0.0.1).
-# Set HOST_BIND=0.0.0.0 to reach it from your LAN — only on
-# a trusted network; the proxy is single-user.
-#
-# Re-running is safe: existing .env (and your encryption key) is preserved,
-# the compose file is refreshed, and the container is updated to :latest.
-
+# The FreeLLMAPI installer moved to https://freellmapi.co/install.sh
+# This shim keeps old `curl ... github.io ... | bash` one-liners working.
set -euo pipefail
-
-INSTALL_DIR="${FREELLMAPI_DIR:-$HOME/freellmapi}"
-PORT="${PORT:-3001}"
-HOST_BIND="${HOST_BIND:-127.0.0.1}"
-IMAGE="ghcr.io/tashfeenahmed/freellmapi:latest"
-
-say() { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
-warn() { printf '\033[1;33mWARN\033[0m %s\n' "$*" >&2; }
-die() { printf '\033[1;31mERROR\033[0m %s\n' "$*" >&2; exit 1; }
-
-# ── 1. prerequisites ─────────────────────────────────────────────────────────
-command -v docker >/dev/null 2>&1 || die "Docker is required. Install it from https://docs.docker.com/get-docker/ and re-run."
-
-if docker compose version >/dev/null 2>&1; then
- COMPOSE=(docker compose)
-elif command -v docker-compose >/dev/null 2>&1; then
- COMPOSE=(docker-compose)
-else
- die "Docker Compose is required (the 'docker compose' plugin or 'docker-compose')."
-fi
-
-docker info >/dev/null 2>&1 || die "Docker daemon isn't running (or you lack permission). Start Docker and re-run."
-
-# ── 2. install dir ───────────────────────────────────────────────────────────
-mkdir -p "$INSTALL_DIR"
-cd "$INSTALL_DIR"
-say "Installing into $INSTALL_DIR"
-
-# ── 3. .env (generated once — your at-rest encryption key lives here) ────────
-if [ -f .env ]; then
- say "Keeping existing .env (encryption key preserved)"
-else
- if command -v openssl >/dev/null 2>&1; then
- KEY="$(openssl rand -hex 32)"
- else
- # /dev/urandom fallback when openssl isn't installed
- KEY="$(od -vN 32 -An -tx1 /dev/urandom | tr -d ' \n')"
- fi
- umask 077
- cat > .env <<EOF
-# Generated by install.sh on $(date -u +%Y-%m-%dT%H:%M:%SZ)
-# At-rest encryption key for your stored provider keys. Losing it means
-# re-entering your provider keys, so back this file up.
-ENCRYPTION_KEY=$KEY
-PORT=$PORT
-HOST_BIND=$HOST_BIND
-EOF
- umask 022
- say "Wrote .env with a fresh ENCRYPTION_KEY"
-fi
-
-# ── 4. compose file (image-only; refreshed on every run) ─────────────────────
-cat > docker-compose.yml <<EOF
-# Written by install.sh — safe to edit; re-running the installer rewrites it.
-services:
- freellmapi:
- image: $IMAGE
- env_file:
- - .env
- environment:
- NODE_ENV: production
- PORT: 3001
- # Bound to localhost by default — FreeLLMAPI is single-user and must not
- # be exposed to the internet. Set HOST_BIND=0.0.0.0 in .env for LAN access.
- ports:
- - "\${HOST_BIND:-127.0.0.1}:\${PORT:-3001}:3001"
- volumes:
- - freellmapi-data:/app/server/data
- restart: unless-stopped
- healthcheck:
- test:
- [
- "CMD",
- "node",
- "-e",
- "fetch('http://127.0.0.1:3001/api/ping').then((res) => { if (!res.ok) process.exit(1); }).catch(() => process.exit(1));"
- ]
- interval: 30s
- timeout: 5s
- start_period: 15s
- retries: 3
-
-volumes:
- freellmapi-data:
-EOF
-
-# ── 5. pull + start ──────────────────────────────────────────────────────────
-say "Pulling $IMAGE"
-"${COMPOSE[@]}" pull --quiet 2>/dev/null || "${COMPOSE[@]}" pull
-say "Starting FreeLLMAPI"
-"${COMPOSE[@]}" up -d
-
-# ── 6. wait for health ───────────────────────────────────────────────────────
-say "Waiting for the server to come up"
-HEALTH_HOST="127.0.0.1"
-[ "$HOST_BIND" != "0.0.0.0" ] && [ "$HOST_BIND" != "127.0.0.1" ] && HEALTH_HOST="$HOST_BIND"
-for i in $(seq 1 30); do
- if curl -fsS "http://$HEALTH_HOST:$PORT/api/ping" >/dev/null 2>&1; then
- HEALTHY=1
- break
- fi
- sleep 2
-done
-
-if [ "${HEALTHY:-0}" = "1" ]; then
- cat <<EOF
-
- FreeLLMAPI is running.
-
- Dashboard http://localhost:$PORT
- Next steps add provider keys on the Keys page, then grab your
- unified API key from the page header — that's the
- Bearer token your OpenAI-compatible client uses.
- API endpoint http://localhost:$PORT/v1
-
- Update cd $INSTALL_DIR && docker compose pull && docker compose up -d
- Logs cd $INSTALL_DIR && docker compose logs -f
- Uninstall cd $INSTALL_DIR && docker compose down -v && cd .. && rm -rf $INSTALL_DIR
-
-EOF
-else
- warn "Container started but the health endpoint didn't answer within 60s."
- warn "Check logs with: cd $INSTALL_DIR && ${COMPOSE[*]} logs -f"
- exit 1
-fi
+exec bash -c "$(curl -fsSL https://freellmapi.co/install.sh)"
diff --git a/docs/logos/cerebras.svg b/docs/logos/cerebras.svg
deleted file mode 100644
index ff9abb60..00000000
--- a/docs/logos/cerebras.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#F55036" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Cerebras</title><path clip-rule="evenodd" d="M14.121 2.701a9.299 9.299 0 000 18.598V22.7c-5.91 0-10.7-4.791-10.7-10.701S8.21 1.299 14.12 1.299V2.7zm4.752 3.677A7.353 7.353 0 109.42 17.643l-.901 1.074a8.754 8.754 0 01-1.08-12.334 8.755 8.755 0 0112.335-1.08l-.901 1.075zm-2.255.844a5.407 5.407 0 00-5.048 9.563l-.656 1.24a6.81 6.81 0 016.358-12.043l-.654 1.24zM14.12 8.539a3.46 3.46 0 100 6.922v1.402a4.863 4.863 0 010-9.726v1.402z"></path><path d="M15.407 10.836a2.24 2.24 0 00-.51-.409 1.084 1.084 0 00-.544-.152c-.255 0-.483.047-.684.14a1.58 1.58 0 00-.84.912c-.074.203-.11.416-.11.631 0 .218.036.43.11.631a1.594 1.594 0 00.84.913c.2.093.43.14.684.14.216 0 .417-.046.602-.135.188-.09.35-.225.475-.392l.928 1.006c-.14.14-.3.261-.482.363a3.367 3.367 0 01-1.083.38c-.17.026-.317.04-.44.04a3.315 3.315 0 01-1.182-.21 2.825 2.825 0 01-.961-.597 2.816 2.816 0 01-.644-.929 2.987 2.987 0 01-.238-1.21c0-.444.08-.847.238-1.21.15-.35.368-.666.643-.929.278-.261.605-.464.962-.596a3.315 3.315 0 011.182-.21c.355 0 .712.068 1.072.204.361.138.685.36.944.649l-.962.97z"></path></svg>
\ No newline at end of file
diff --git a/docs/logos/cloudflare.svg b/docs/logos/cloudflare.svg
deleted file mode 100644
index 6ab0b7d5..00000000
--- a/docs/logos/cloudflare.svg
+++ /dev/null
@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -70 256 256" version="1.1" preserveAspectRatio="xMidYMid">
- <g transform="translate(0.000000, -1.000000)">
- <path d="M202.3569,50.394 L197.0459,48.27 C172.0849,104.434 72.7859,70.289 66.8109,86.997 C65.8149,98.283 121.0379,89.143 160.5169,91.056 C172.5559,91.639 178.5929,100.727 173.4809,115.54 L183.5499,115.571 C195.1649,79.362 232.2329,97.841 233.7819,85.891 C231.2369,78.034 191.1809,85.891 202.3569,50.394 Z" fill="#FFFFFF"/>
- <path d="M176.332,109.3483 C177.925,104.0373 177.394,98.7263 174.739,95.5393 C172.083,92.3523 168.365,90.2283 163.585,89.6973 L71.17,88.6343 C70.639,88.6343 70.108,88.1033 69.577,88.1033 C69.046,87.5723 69.046,87.0413 69.577,86.5103 C70.108,85.4483 70.639,84.9163 71.701,84.9163 L164.647,83.8543 C175.801,83.3233 187.486,74.2943 191.734,63.6723 L197.046,49.8633 C197.046,49.3313 197.577,48.8003 197.046,48.2693 C191.203,21.1823 166.772,0.9993 138.091,0.9993 C111.535,0.9993 88.697,17.9953 80.73,41.8963 C75.419,38.1783 69.046,36.0533 61.61,36.5853 C48.863,37.6473 38.772,48.2693 37.178,61.0163 C36.647,64.2033 37.178,67.3903 37.71,70.5763 C16.996,71.1073 0,88.1033 0,109.3483 C0,111.4723 0,113.0663 0.531,115.1903 C0.531,116.2533 1.593,116.7843 2.125,116.7843 L172.614,116.7843 C173.676,116.7843 174.739,116.2533 174.739,115.1903 L176.332,109.3483 Z" fill="#F4811F"/>
- <path d="M205.5436,49.8628 L202.8876,49.8628 C202.3566,49.8628 201.8256,50.3938 201.2946,50.9248 L197.5766,63.6718 C195.9836,68.9828 196.5146,74.2948 199.1706,77.4808 C201.8256,80.6678 205.5436,82.7918 210.3236,83.3238 L229.9756,84.3858 C230.5066,84.3858 231.0376,84.9168 231.5686,84.9168 C232.0996,85.4478 232.0996,85.9788 231.5686,86.5098 C231.0376,87.5728 230.5066,88.1038 229.4436,88.1038 L209.2616,89.1658 C198.1076,89.6968 186.4236,98.7258 182.1746,109.3478 L181.1116,114.1288 C180.5806,114.6598 181.1116,115.7218 182.1746,115.7218 L252.2826,115.7218 C253.3446,115.7218 253.8756,115.1908 253.8756,114.1288 C254.9376,109.8798 255.9996,105.0998 255.9996,100.3188 C255.9996,72.7008 233.1616,49.8628 205.5436,49.8628" fill="#FAAD3F"/>
- </g>
-</svg>
diff --git a/docs/logos/cohere.svg b/docs/logos/cohere.svg
deleted file mode 100644
index 4f02d7de..00000000
--- a/docs/logos/cohere.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#39594D" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Cohere</title><path clip-rule="evenodd" d="M8.128 14.099c.592 0 1.77-.033 3.398-.703 1.897-.781 5.672-2.2 8.395-3.656 1.905-1.018 2.74-2.366 2.74-4.18A4.56 4.56 0 0018.1 1H7.549A6.55 6.55 0 001 7.55c0 3.617 2.745 6.549 7.128 6.549z"></path><path clip-rule="evenodd" d="M9.912 18.61a4.387 4.387 0 012.705-4.052l3.323-1.38c3.361-1.394 7.06 1.076 7.06 4.715a5.104 5.104 0 01-5.105 5.104l-3.597-.001a4.386 4.386 0 01-4.386-4.387z"></path><path d="M4.776 14.962A3.775 3.775 0 001 18.738v.489a3.776 3.776 0 007.551 0v-.49a3.775 3.775 0 00-3.775-3.775z"></path></svg>
\ No newline at end of file
diff --git a/docs/logos/github.svg b/docs/logos/github.svg
deleted file mode 100644
index 81920ca3..00000000
--- a/docs/logos/github.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#181717" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>GitHub</title><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
\ No newline at end of file
diff --git a/docs/logos/google.svg b/docs/logos/google.svg
deleted file mode 100644
index e15e53ce..00000000
--- a/docs/logos/google.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#8E75B2" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Google Gemini</title><path d="M11.04 19.32Q12 21.51 12 24q0-2.49.93-4.68.96-2.19 2.58-3.81t3.81-2.55Q21.51 12 24 12q-2.49 0-4.68-.93a12.3 12.3 0 0 1-3.81-2.58 12.3 12.3 0 0 1-2.58-3.81Q12 2.49 12 0q0 2.49-.96 4.68-.93 2.19-2.55 3.81a12.3 12.3 0 0 1-3.81 2.58Q2.49 12 0 12q2.49 0 4.68.96 2.19.93 3.81 2.55t2.55 3.81"/></svg>
\ No newline at end of file
diff --git a/docs/logos/groq.svg b/docs/logos/groq.svg
deleted file mode 100644
index 88ac80bd..00000000
--- a/docs/logos/groq.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#F55036" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Groq</title><path d="M12.036 2c-3.853-.035-7 3-7.036 6.781-.035 3.782 3.055 6.872 6.908 6.907h2.42v-2.566h-2.292c-2.407.028-4.38-1.866-4.408-4.23-.029-2.362 1.901-4.298 4.308-4.326h.1c2.407 0 4.358 1.915 4.365 4.278v6.305c0 2.342-1.944 4.25-4.323 4.279a4.375 4.375 0 01-3.033-1.252l-1.851 1.818A7 7 0 0012.029 22h.092c3.803-.056 6.858-3.083 6.879-6.816v-6.5C18.907 4.963 15.817 2 12.036 2z"></path></svg>
\ No newline at end of file
diff --git a/docs/logos/mistral.svg b/docs/logos/mistral.svg
deleted file mode 100644
index 00ee1b9e..00000000
--- a/docs/logos/mistral.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#FA520F" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Mistral AI</title><path d="M17.143 3.429v3.428h-3.429v3.429h-3.428V6.857H6.857V3.43H3.43v13.714H0v3.428h10.286v-3.428H6.857v-3.429h3.429v3.429h3.429v-3.429h3.428v3.429h-3.428v3.428H24v-3.428h-3.43V3.429z"/></svg>
\ No newline at end of file
diff --git a/docs/logos/nvidia.svg b/docs/logos/nvidia.svg
deleted file mode 100644
index e427e2ce..00000000
--- a/docs/logos/nvidia.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#76B900" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>NVIDIA</title><path d="M8.948 8.798v-1.43a6.7 6.7 0 0 1 .424-.018c3.922-.124 6.493 3.374 6.493 3.374s-2.774 3.851-5.75 3.851c-.398 0-.787-.062-1.158-.185v-4.346c1.528.185 1.837.857 2.747 2.385l2.04-1.714s-1.492-1.952-4-1.952a6.016 6.016 0 0 0-.796.035m0-4.735v2.138l.424-.027c5.45-.185 9.01 4.47 9.01 4.47s-4.08 4.964-8.33 4.964c-.37 0-.733-.035-1.095-.097v1.325c.3.035.61.062.91.062 3.957 0 6.82-2.023 9.593-4.408.459.371 2.34 1.263 2.73 1.652-2.633 2.208-8.772 3.984-12.253 3.984-.335 0-.653-.018-.971-.053v1.864H24V4.063zm0 10.326v1.131c-3.657-.654-4.673-4.46-4.673-4.46s1.758-1.944 4.673-2.262v1.237H8.94c-1.528-.186-2.73 1.245-2.73 1.245s.68 2.412 2.739 3.11M2.456 10.9s2.164-3.197 6.5-3.533V6.201C4.153 6.59 0 10.653 0 10.653s2.35 6.802 8.948 7.42v-1.237c-4.84-.6-6.492-5.936-6.492-5.936z"/></svg>
\ No newline at end of file
diff --git a/docs/logos/openrouter.svg b/docs/logos/openrouter.svg
deleted file mode 100644
index 5cee81ca..00000000
--- a/docs/logos/openrouter.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#6366F1" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>OpenRouter</title><path d="M16.778 1.844v1.919q-.569-.026-1.138-.032-.708-.008-1.415.037c-1.93.126-4.023.728-6.149 2.237-2.911 2.066-2.731 1.95-4.14 2.75-.396.223-1.342.574-2.185.798-.841.225-1.753.333-1.751.333v4.229s.768.108 1.61.333c.842.224 1.789.575 2.185.799 1.41.798 1.228.683 4.14 2.75 2.126 1.509 4.22 2.11 6.148 2.236.88.058 1.716.041 2.555.005v1.918l7.222-4.168-7.222-4.17v2.176c-.86.038-1.611.065-2.278.021-1.364-.09-2.417-.357-3.979-1.465-2.244-1.593-2.866-2.027-3.68-2.508.889-.518 1.449-.906 3.822-2.59 1.56-1.109 2.614-1.377 3.978-1.466.667-.044 1.418-.017 2.278.02v2.176L24 6.014Z"/></svg>
\ No newline at end of file
diff --git a/docs/logos/sambanova.jpg b/docs/logos/sambanova.jpg
deleted file mode 100644
index a15ecf80..00000000
Binary files a/docs/logos/sambanova.jpg and /dev/null differ
diff --git a/docs/logos/zai.svg b/docs/logos/zai.svg
deleted file mode 100644
index ac4c8f26..00000000
--- a/docs/logos/zai.svg
+++ /dev/null
@@ -1,12 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 30 30" xml:space="preserve">
-<style type="text/css">
- .st23{fill:#FFFFFF;}
- .st194{fill:#2D2D2D;stroke:#FFFFFF;stroke-width:0.6317;stroke-miterlimit:10;}
-</style>
-<g>
- <path class="st194" d="M24.51,28.51H5.49c-2.21,0-4-1.79-4-4V5.49c0-2.21,1.79-4,4-4h19.03c2.21,0,4,1.79,4,4v19.03 C28.51,26.72,26.72,28.51,24.51,28.51z"/>
- <path class="st23" d="M15.47,7.1l-1.3,1.85c-0.2,0.29-0.54,0.47-0.9,0.47h-7.1V7.09C6.16,7.1,15.47,7.1,15.47,7.1z"/>
- <polygon class="st23" points="24.3,7.1 13.14,22.91 5.7,22.91 16.86,7.1"/>
- <path class="st23" d="M14.53,22.91l1.31-1.86c0.2-0.29,0.54-0.47,0.9-0.47h7.09v2.33H14.53z"/>
-</g>
-</svg>
diff --git a/docs/og.png b/docs/og.png
deleted file mode 100644
index 44f17a3f..00000000
Binary files a/docs/og.png and /dev/null differ
diff --git a/docs/og.svg b/docs/og.svg
deleted file mode 100644
index d635274a..00000000
--- a/docs/og.svg
+++ /dev/null
@@ -1,18 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" width="1200" height="630">
- <defs>
- <linearGradient id="grad" x1="0" y1="0" x2="1" y2="0.3">
- <stop offset="0" stop-color="#a78bfa"/>
- <stop offset="1" stop-color="#22d3ee"/>
- </linearGradient>
- </defs>
- <rect width="1200" height="630" fill="#0a0a0a"/>
- <!-- logo mark -->
- <g transform="translate(600 138)">
- <circle r="46" fill="#ffffff"/>
- <circle r="17" fill="#0a0a0a"/>
- </g>
- <text x="600" y="250" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="34" font-weight="700" letter-spacing="2" fill="#fafafa">FreeLLMAPI</text>
- <text x="600" y="430" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="210" font-weight="800" letter-spacing="-6" fill="url(#grad)">1.7B</text>
- <text x="600" y="498" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="46" font-weight="600" fill="#fafafa">free LLM tokens / month</text>
- <text x="600" y="560" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="29" font-weight="500" fill="#a1a1aa">16 providers · 100+ models · OpenAI-compatible · self-hosted</text>
-</svg>
diff --git a/docs/success.html b/docs/success.html
new file mode 100644
index 00000000..5b802cc7
--- /dev/null
+++ b/docs/success.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>FreeLLMAPI has moved to freellmapi.co</title>
+<meta name="robots" content="noindex" />
+</head>
+<body>
+ <p>This page moved to <a href="https://freellmapi.co/success">freellmapi.co</a>. Redirecting&hellip;</p>
+ <script>location.replace('https://freellmapi.co/success' + location.search);</script>
+</body>
+</html>
diff --git a/server/package.json b/server/package.json
index 575f95bb..57f011ef 100644
--- a/server/package.json
+++ b/server/package.json
@@ -8,7 +8,8 @@
"build": "tsc",
"start": "node dist/index.js",
"test": "vitest run --pool=forks --fileParallelism=false",
- "test:watch": "vitest"
+ "test:watch": "vitest",
+ "export-catalog": "tsx src/scripts/export-catalog.ts"
},
"dependencies": {
"@freellmapi/shared": "*",
diff --git a/server/src/__tests__/services/catalog-sync.test.ts b/server/src/__tests__/services/catalog-sync.test.ts
new file mode 100644
index 00000000..0f2b516b
--- /dev/null
+++ b/server/src/__tests__/services/catalog-sync.test.ts
@@ -0,0 +1,177 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { applyCatalog } from '../../services/catalog-sync.js';
+
+// applyCatalog is the write path between the published catalog and the live
+// router DB. These tests lock its contract: catalog metadata always wins, the
+// user's manual disables survive, custom-provider models are untouchable, and
+// disappeared models are removed in FK-safe order.
+
+type AnyCatalog = Parameters<typeof applyCatalog>[1];
+
+function baseModel(over: Partial<AnyCatalog['models'][number]> = {}): AnyCatalog['models'][number] {
+ return {
+ platform: 'groq',
+ modelId: 'test-model',
+ displayName: 'Test Model',
+ intelligenceRank: 10,
+ speedRank: 5,
+ sizeLabel: 'Medium',
+ limits: { rpm: 30, rpd: 1000, tpm: 6000, tpd: null },
+ monthlyTokenBudget: '~1M',
+ contextWindow: 8192,
+ enabled: true,
+ supportsVision: false,
+ supportsTools: true,
+ ...over,
+ };
+}
+
+function catalogOf(models: AnyCatalog['models'], quirks: AnyCatalog['quirks'] = []): AnyCatalog {
+ return {
+ version: '2099.01.01',
+ generatedAt: new Date().toISOString(),
+ tier: 'live',
+ models,
+ quirks,
+ };
+}
+
+/** Snapshot every catalog-managed model as catalog entries so applyCatalog keeps them. */
+function existingAsCatalogModels(): AnyCatalog['models'] {
+ const rows = getDb()
+ .prepare(
+ `SELECT platform, model_id, display_name, intelligence_rank, speed_rank, size_label,
+ rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window,
+ enabled, supports_vision, supports_tools
+ FROM models WHERE platform != 'custom' AND key_id IS NULL`,
+ )
+ .all() as Array<Record<string, unknown>>;
+ return rows.map((r) =>
+ baseModel({
+ platform: r.platform as string,
+ modelId: r.model_id as string,
+ displayName: r.display_name as string,
+ intelligenceRank: r.intelligence_rank as number,
+ speedRank: r.speed_rank as number,
+ sizeLabel: r.size_label as string,
+ limits: {
+ rpm: r.rpm_limit as number | null,
+ rpd: r.rpd_limit as number | null,
+ tpm: r.tpm_limit as number | null,
+ tpd: r.tpd_limit as number | null,
+ },
+ monthlyTokenBudget: r.monthly_token_budget as string,
+ contextWindow: r.context_window as number | null,
+ enabled: (r.enabled as number) === 1,
+ supportsVision: (r.supports_vision as number) === 1,
+ supportsTools: (r.supports_tools as number) === 1,
+ }),
+ );
+}
+
+describe('applyCatalog', () => {
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ it('inserts a new model with a fallback_config row', () => {
+ const models = existingAsCatalogModels();
+ models.push(baseModel({ modelId: 'brand-new-model', displayName: 'Brand New' }));
+
+ const counts = applyCatalog(getDb(), catalogOf(models));
+ expect(counts.inserted).toBe(1);
+
+ const row = getDb()
+ .prepare("SELECT id, enabled FROM models WHERE platform = 'groq' AND model_id = 'brand-new-model'")
+ .get() as { id: number; enabled: number };
+ expect(row.enabled).toBe(1);
+ const fb = getDb().prepare('SELECT id FROM fallback_config WHERE model_db_id = ?').get(row.id);
+ expect(fb).toBeTruthy();
+ });
+
+ it('updates metadata in place and respects the enabled policy', () => {
+ const models = existingAsCatalogModels();
+ const target = models.find((m) => m.modelId === 'brand-new-model')!;
+
+ // User disables the model locally; catalog still says enabled -> stays off.
+ getDb()
+ .prepare("UPDATE models SET enabled = 0 WHERE platform = 'groq' AND model_id = 'brand-new-model'")
+ .run();
+ target.displayName = 'Brand New v2';
+ target.limits = { rpm: 99, rpd: null, tpm: null, tpd: null };
+ applyCatalog(getDb(), catalogOf(models));
+
+ let row = getDb()
+ .prepare("SELECT display_name, rpm_limit, enabled FROM models WHERE platform = 'groq' AND model_id = 'brand-new-model'")
+ .get() as { display_name: string; rpm_limit: number; enabled: number };
+ expect(row.display_name).toBe('Brand New v2');
+ expect(row.rpm_limit).toBe(99);
+ expect(row.enabled).toBe(0); // local disable survives
+
+ // Catalog disables (dead upstream) -> force off even if user re-enabled.
+ getDb()
+ .prepare("UPDATE models SET enabled = 1 WHERE platform = 'groq' AND model_id = 'brand-new-model'")
+ .run();
+ target.enabled = false;
+ applyCatalog(getDb(), catalogOf(models));
+ row = getDb()
+ .prepare("SELECT display_name, rpm_limit, enabled FROM models WHERE platform = 'groq' AND model_id = 'brand-new-model'")
+ .get() as typeof row;
+ expect(row.enabled).toBe(0);
+ });
+
+ it('removes models that left the catalog (and their fallback rows)', () => {
+ const models = existingAsCatalogModels().filter((m) => m.modelId !== 'brand-new-model');
+ const before = getDb()
+ .prepare("SELECT id FROM models WHERE model_id = 'brand-new-model'")
+ .get() as { id: number };
+
+ const counts = applyCatalog(getDb(), catalogOf(models));
+ expect(counts.removed).toBe(1);
+ expect(getDb().prepare("SELECT id FROM models WHERE model_id = 'brand-new-model'").get()).toBeUndefined();
+ expect(getDb().prepare('SELECT id FROM fallback_config WHERE model_db_id = ?').get(before.id)).toBeUndefined();
+ });
+
+ it('never touches custom-provider models', () => {
+ getDb()
+ .prepare(
+ `INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, size_label, enabled)
+ VALUES ('custom', 'my-local-model', 'My Local', 50, 50, 'Custom', 1)`,
+ )
+ .run();
+
+ // Catalog without the custom model: it must survive the delete pass.
+ applyCatalog(getDb(), catalogOf(existingAsCatalogModels().filter((m) => m.platform !== 'custom')));
+ const row = getDb().prepare("SELECT enabled FROM models WHERE platform = 'custom'").get() as { enabled: number };
+ expect(row.enabled).toBe(1);
+ });
+
+ it('skips models for platforms this binary has no provider for', () => {
+ const models = existingAsCatalogModels();
+ models.push(baseModel({ platform: 'some-future-provider', modelId: 'future-model' }));
+ const counts = applyCatalog(getDb(), catalogOf(models));
+ expect(counts.skippedUnknownPlatform).toBeGreaterThanOrEqual(1);
+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'some-future-provider'").get()).toBeUndefined();
+ });
+
+ it('replaces quirks wholesale', () => {
+ const quirks: AnyCatalog['quirks'] = [
+ {
+ slug: 'fresh-quirk',
+ title: 'Fresh quirk',
+ body: 'New knowledge from the catalog.',
+ severity: 'warning',
+ targets: [{ platform: 'groq', modelGlob: null }],
+ },
+ ];
+ const counts = applyCatalog(getDb(), catalogOf(existingAsCatalogModels(), quirks));
+ expect(counts.quirks).toBe(1);
+
+ const all = getDb().prepare('SELECT slug FROM quirks').all() as { slug: string }[];
+ expect(all.map((q) => q.slug)).toEqual(['fresh-quirk']);
+ const targets = getDb().prepare('SELECT platform, model_glob FROM quirk_targets').all();
+ expect(targets).toEqual([{ platform: 'groq', model_glob: null }]);
+ });
+});
diff --git a/server/src/__tests__/services/quirks.test.ts b/server/src/__tests__/services/quirks.test.ts
new file mode 100644
index 00000000..2554331d
--- /dev/null
+++ b/server/src/__tests__/services/quirks.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { resolveQuirksByModel, quirkKey, listQuirkDefinitions } from '../../services/quirks.js';
+
+// The quirks layer is the catalog product's data integrity: one quirk is
+// applied to many models by selector parameters (migrateQuirksV1). These lock
+// the platform / glob / global selectors and the resolver that the catalog
+// export depends on.
+describe('quirks resolution (migrateQuirksV1)', () => {
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ function slugsFor(platform: string, modelId: string): string[] {
+ return (resolveQuirksByModel().get(quirkKey(platform, modelId)) ?? []).map((q) => q.slug);
+ }
+
+ it('applies a platform-level quirk to every model on that platform', () => {
+ const nvidiaModels = getDb()
+ .prepare("SELECT model_id FROM models WHERE platform = 'nvidia'")
+ .all() as { model_id: string }[];
+ expect(nvidiaModels.length).toBeGreaterThan(0);
+ for (const m of nvidiaModels) {
+ expect(slugsFor('nvidia', m.model_id)).toContain('nvidia-credits-based');
+ }
+ });
+
+ it('applies a glob quirk only to matching model ids', () => {
+ // or-ultra-hangs targets openrouter '*nemotron-3-ultra*'
+ const ultra = getDb()
+ .prepare("SELECT model_id FROM models WHERE platform = 'openrouter' AND model_id GLOB '*nemotron-3-ultra*'")
+ .get() as { model_id: string } | undefined;
+ if (ultra) expect(slugsFor('openrouter', ultra.model_id)).toContain('or-ultra-hangs');
+
+ // A non-matching openrouter model must NOT pick it up.
+ const other = getDb()
+ .prepare("SELECT model_id FROM models WHERE platform = 'openrouter' AND model_id NOT GLOB '*nemotron-3-ultra*'")
+ .get() as { model_id: string } | undefined;
+ if (other) expect(slugsFor('openrouter', other.model_id)).not.toContain('or-ultra-hangs');
+ });
+
+ it('does not leak a platform quirk onto other platforms', () => {
+ const google = getDb()
+ .prepare("SELECT model_id FROM models WHERE platform = 'google'")
+ .get() as { model_id: string } | undefined;
+ if (google) expect(slugsFor('google', google.model_id)).not.toContain('cloudflare-key-format');
+ });
+
+ it('lists quirk definitions with their selector parameters', () => {
+ const defs = listQuirkDefinitions();
+ const keyless = defs.find((d) => d.slug === 'keyless-anonymous');
+ expect(keyless).toBeDefined();
+ // keyless-anonymous targets three keyless platforms.
+ const platforms = keyless!.targets.map((t) => t.platform).sort();
+ expect(platforms).toEqual(['kilo', 'llm7', 'pollinations']);
+ });
+
+ it('resolves stably and dedups overlapping selectors', () => {
+ // A model matched by two of a quirk's selectors must list it once (DISTINCT).
+ const a = resolveQuirksByModel();
+ const b = resolveQuirksByModel();
+ expect(a.size).toBe(b.size);
+ for (const [key, quirks] of a) {
+ const slugs = quirks.map((q) => q.slug);
+ expect(new Set(slugs).size).toBe(slugs.length); // no duplicates
+ expect(b.get(key)!.map((q) => q.slug)).toEqual(slugs); // stable
+ }
+ });
+});
diff --git a/server/src/app.ts b/server/src/app.ts
index e04c1d61..f89de492 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -12,6 +12,7 @@ import { embeddingsRouter } from './routes/embeddings.js';
import { analyticsRouter } from './routes/analytics.js';
import { healthRouter } from './routes/health.js';
import { settingsRouter } from './routes/settings.js';
+import { premiumRouter } from './routes/premium.js';
import { authRouter } from './routes/auth.js';
import { requireAuth } from './middleware/requireAuth.js';
import { createProxyRateLimiter } from './middleware/rateLimit.js';
@@ -68,6 +69,7 @@ export function createApp() {
app.use('/api/analytics', requireAuth, analyticsRouter);
app.use('/api/health', requireAuth, healthRouter);
app.use('/api/settings', requireAuth, settingsRouter);
+ app.use('/api/premium', requireAuth, premiumRouter);
// OpenAI-compatible proxy. Per-IP rate limiting (#35 item #6) runs first so
// it throttles unauthenticated brute-force / flood attempts before any
diff --git a/server/src/db/migrations.ts b/server/src/db/migrations.ts
index 716453c5..1bdf42bd 100644
--- a/server/src/db/migrations.ts
+++ b/server/src/db/migrations.ts
@@ -36,6 +36,7 @@ export function migrateDbSchema(db: Database.Database) {
// (drives the realistic "Est. savings" analytics stat).
applyModelPricing(db);
migrateEmbeddingsV1(db);
+ migrateQuirksV1(db);
ensureUnifiedKey(db);
}
@@ -1923,6 +1924,142 @@ function migrateEmbeddingsV1(db: Database.Database) {
}
}
+/**
+ * Quirks V1 (June 2026): promote the catalog's free-form "quirks" out of code
+ * comments into structured, reusable data so the catalog server can ship them.
+ *
+ * A quirk is defined ONCE (slug, title, body, severity) and applied to models
+ * by SELECTOR PARAMETERS rather than hand-attached per model — because one
+ * quirk routinely covers many models (a whole platform's keyless access, an
+ * entire model family that hangs upstream, etc.). Each row in quirk_targets is
+ * one selector; a NULL field is a wildcard:
+ *
+ * platform NULL, model_glob NULL -> every model (global note)
+ * platform set, model_glob NULL -> every model on that platform
+ * platform set, model_glob set -> that platform's models whose id GLOBs
+ * platform NULL, model_glob set -> any model whose id GLOBs (cross-platform)
+ *
+ * Resolution (see services/quirks.ts) is therefore:
+ * (platform IS NULL OR platform = m.platform)
+ * AND (model_glob IS NULL OR m.model_id GLOB model_glob)
+ *
+ * GLOB (not LIKE) so the selectors read like the model-family rules elsewhere
+ * in this file ('*nemotron-3-ultra*'). Severity drives client display:
+ * 'info' (neutral note), 'warning' (works but caveated), 'blocker' (knowingly
+ * unusable / disabled). Idempotent: tables are IF NOT EXISTS and the seed is a
+ * reset-then-insert of the curated set, so editing a seeded quirk in code wins
+ * on next boot while operator-added quirks (new slugs) are left untouched.
+ */
+function migrateQuirksV1(db: Database.Database) {
+ db.exec(`
+ CREATE TABLE IF NOT EXISTS quirks (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ slug TEXT NOT NULL UNIQUE,
+ title TEXT NOT NULL,
+ body TEXT NOT NULL DEFAULT '',
+ severity TEXT NOT NULL DEFAULT 'info',
+ created_at_ms INTEGER NOT NULL,
+ updated_at_ms INTEGER NOT NULL
+ );
+ CREATE TABLE IF NOT EXISTS quirk_targets (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ quirk_id INTEGER NOT NULL REFERENCES quirks(id) ON DELETE CASCADE,
+ platform TEXT,
+ model_glob TEXT
+ );
+ CREATE INDEX IF NOT EXISTS idx_quirk_targets_quirk ON quirk_targets(quirk_id);
+ `);
+
+ // Curated seed — each entry is one quirk plus the selector parameters that
+ // apply it. Sourced from the catalog's existing code comments (V20–V24).
+ type Seed = {
+ slug: string;
+ title: string;
+ body: string;
+ severity: 'info' | 'warning' | 'blocker';
+ targets: Array<{ platform?: string; modelGlob?: string }>;
+ };
+ const seeds: Seed[] = [
+ {
+ slug: 'keyless-anonymous',
+ title: 'No API key required',
+ body: 'Routes anonymously — the catalog ships a keyless sentinel row and calls work with no account or key.',
+ severity: 'info',
+ targets: [{ platform: 'kilo' }, { platform: 'llm7' }, { platform: 'pollinations' }],
+ },
+ {
+ slug: 'cloudflare-key-format',
+ title: 'Key is account_id:token',
+ body: 'Cloudflare Workers AI authenticates with a combined credential in the form "account_id:token", not a bare token.',
+ severity: 'info',
+ targets: [{ platform: 'cloudflare' }],
+ },
+ {
+ slug: 'nvidia-credits-based',
+ title: 'Credit-based, not recurring-free',
+ body: 'NVIDIA NIM moved to a credit model in 2025; the free allotment is a depleting trial, not a recurring monthly tier. Disabled by default.',
+ severity: 'warning',
+ targets: [{ platform: 'nvidia' }],
+ },
+ {
+ slug: 'nim-gemma-hung',
+ title: 'NIM gemma route hangs',
+ body: 'The NVIDIA NIM gemma endpoint is listed but hangs (capacity starvation plus an upstream FlashAttention bug). Paused; probe with a 120s timeout before re-enabling.',
+ severity: 'blocker',
+ targets: [{ platform: 'nvidia', modelGlob: '*gemma*' }],
+ },
+ {
+ slug: 'or-ultra-hangs',
+ title: 'OpenRouter ultra route hangs',
+ body: 'nemotron-3-ultra (550B) on OpenRouter takes 180s+ even on trivial prompts (heavily congested), so its OR row is seeded disabled. Use the OpenCode Zen route instead.',
+ severity: 'warning',
+ targets: [{ platform: 'openrouter', modelGlob: '*nemotron-3-ultra*' }],
+ },
+ {
+ slug: 'zen-serves-ultra-fast',
+ title: 'Zen serves the 550B fast',
+ body: 'OpenCode Zen serves nemotron-3-ultra in ~2s with working tool calls where the OpenRouter route hangs — the live-verified path for this model.',
+ severity: 'info',
+ targets: [{ platform: 'opencode', modelGlob: '*nemotron-3-ultra*' }],
+ },
+ {
+ slug: 'zhipu-shared-key',
+ title: 'Works with existing Zhipu key',
+ body: 'glm-4.6v-flash is listed Free on Z.AI and answers 200 with the existing bigmodel.cn key; vision and structured tool calls both live-verified.',
+ severity: 'info',
+ targets: [{ platform: 'zhipu', modelGlob: '*glm-4.6v*' }],
+ },
+ ];
+
+ const now = Date.now();
+ const upsertQuirk = db.prepare(`
+ INSERT INTO quirks (slug, title, body, severity, created_at_ms, updated_at_ms)
+ VALUES (@slug, @title, @body, @severity, @now, @now)
+ ON CONFLICT(slug) DO UPDATE SET
+ title = excluded.title,
+ body = excluded.body,
+ severity = excluded.severity,
+ updated_at_ms = excluded.updated_at_ms
+ `);
+ const getId = db.prepare('SELECT id FROM quirks WHERE slug = ?');
+ const clearTargets = db.prepare('DELETE FROM quirk_targets WHERE quirk_id = ?');
+ const addTarget = db.prepare(
+ 'INSERT INTO quirk_targets (quirk_id, platform, model_glob) VALUES (?, ?, ?)',
+ );
+
+ const apply = db.transaction(() => {
+ for (const s of seeds) {
+ upsertQuirk.run({ slug: s.slug, title: s.title, body: s.body, severity: s.severity, now });
+ const { id } = getId.get(s.slug) as { id: number };
+ // Reset the curated quirk's selectors so edits in code take effect, but
+ // leave quirks/targets with unknown slugs (operator-added) alone.
+ clearTargets.run(id);
+ for (const t of s.targets) addTarget.run(id, t.platform ?? null, t.modelGlob ?? null);
+ }
+ });
+ apply();
+}
+
/** Append any models not yet in the fallback chain, lowest priority, ordered by
* intelligence_rank. Shared by the recent model migrations (V18–V20). */
function backfillFallback(db: Database.Database) {
diff --git a/server/src/index.ts b/server/src/index.ts
index efb7329e..de7d172e 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -2,6 +2,7 @@ import './env.js';
import { createApp } from './app.js';
import { initDb } from './db/index.js';
import { startHealthChecker } from './services/health.js';
+import { startCatalogSync } from './services/catalog-sync.js';
const PORT = process.env.PORT ?? 3001;
// Dual-stack ('::') by default so the dashboard is reachable over both IPv4
@@ -18,6 +19,7 @@ async function main() {
console.log(`Server running on http://${display}:${PORT}`);
console.log(`Proxy endpoint: http://${display}:${PORT}/v1/chat/completions`);
startHealthChecker();
+ startCatalogSync();
};
const server = app.listen(Number(PORT), HOST, onReady(HOST));
diff --git a/server/src/routes/premium.ts b/server/src/routes/premium.ts
new file mode 100644
index 00000000..92eeb164
--- /dev/null
+++ b/server/src/routes/premium.ts
@@ -0,0 +1,126 @@
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import { getSetting, setSetting, getDb } from '../db/index.js';
+import {
+ SETTING_LICENSE_KEY,
+ SETTING_LICENSE_STATUS,
+ catalogBaseUrl,
+ getCachedLicenseStatus,
+ getSyncState,
+ refreshLicenseStatus,
+ syncCatalog,
+} from '../services/catalog-sync.js';
+
+export const premiumRouter = Router();
+
+function maskKey(key: string): string {
+ if (key.length <= 10) return key;
+ return `${key.slice(0, 7)}…${key.slice(-4)}`;
+}
+
+function statusPayload() {
+ const key = getSetting(SETTING_LICENSE_KEY);
+ return {
+ hasKey: Boolean(key),
+ maskedKey: key ? maskKey(key) : null,
+ license: getCachedLicenseStatus(),
+ catalog: getSyncState(),
+ // Where "Go Premium" / "recover key" links point. Overridable for forks.
+ siteUrl: (process.env.PREMIUM_SITE_URL ?? 'https://freellmapi.co').replace(/\/$/, ''),
+ };
+}
+
+/** GET /api/premium — everything the Premium page renders. */
+premiumRouter.get('/', (_req: Request, res: Response) => {
+ res.json(statusPayload());
+});
+
+/**
+ * POST /api/premium/key { key } — activate a license key.
+ * Validates against the catalog service first; only a key the service accepts
+ * is stored. A live-tier sync is kicked off right away so the upgrade is
+ * visible within seconds, not at the next 12h poll.
+ */
+premiumRouter.post('/key', async (req: Request, res: Response) => {
+ const key = typeof req.body?.key === 'string' ? req.body.key.trim() : '';
+ if (key.length < 8) {
+ res.status(400).json({ error: 'Enter the license key from your purchase email.' });
+ return;
+ }
+
+ let result: { valid: boolean; plan: string | null; status: string | null; expiresAt: string | null; reason?: string };
+ try {
+ const r = await fetch(`${catalogBaseUrl()}/v1/license/activate`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ key }),
+ signal: AbortSignal.timeout(15000),
+ });
+ result = (await r.json()) as typeof result;
+ } catch {
+ res.status(502).json({ error: 'Could not reach the license service. Check your connection and try again.' });
+ return;
+ }
+
+ if (!result.valid) {
+ const reasons: Record<string, string> = {
+ unknown_key: 'That key was not recognized. Check for typos, or use key recovery on the website.',
+ expired: 'That key has expired. Renew on the website to keep the live catalog.',
+ canceled: 'That subscription was canceled. Re-subscribe on the website to reactivate.',
+ refunded: 'That purchase was refunded, so the key is no longer active.',
+ };
+ res.status(400).json({ error: reasons[result.reason ?? ''] ?? 'That key is not active.' });
+ return;
+ }
+
+ setSetting(SETTING_LICENSE_KEY, key);
+ await refreshLicenseStatus();
+ const sync = await syncCatalog(true);
+ res.json({ ...statusPayload(), sync });
+});
+
+/** DELETE /api/premium/key — deactivate locally (the purchase itself is untouched). */
+premiumRouter.delete('/key', async (_req: Request, res: Response) => {
+ const db = getDb();
+ db.prepare('DELETE FROM settings WHERE key IN (?, ?)').run(SETTING_LICENSE_KEY, SETTING_LICENSE_STATUS);
+ // Drop back to the free tier in the background; failure just means the next
+ // scheduled poll handles it.
+ void syncCatalog(true);
+ res.json(statusPayload());
+});
+
+/** POST /api/premium/sync — manual "check for updates now". */
+premiumRouter.post('/sync', async (_req: Request, res: Response) => {
+ await refreshLicenseStatus();
+ const sync = await syncCatalog(true);
+ res.json({ ...statusPayload(), sync });
+});
+
+/**
+ * POST /api/premium/portal — Stripe Billing Portal session for the stored key.
+ * This is how an annual subscriber cancels, updates a card, or pulls invoices,
+ * entirely self-serve.
+ */
+premiumRouter.post('/portal', async (_req: Request, res: Response) => {
+ const key = getSetting(SETTING_LICENSE_KEY);
+ if (!key) {
+ res.status(400).json({ error: 'No license key configured.' });
+ return;
+ }
+ try {
+ const r = await fetch(`${catalogBaseUrl()}/v1/portal`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ key }),
+ signal: AbortSignal.timeout(15000),
+ });
+ const body = (await r.json()) as { url?: string; error?: string };
+ if (!r.ok || !body.url) {
+ res.status(502).json({ error: body.error ?? 'Could not open the billing portal.' });
+ return;
+ }
+ res.json({ url: body.url });
+ } catch {
+ res.status(502).json({ error: 'Could not reach the billing service. Try again shortly.' });
+ }
+});
diff --git a/server/src/scripts/export-catalog.ts b/server/src/scripts/export-catalog.ts
new file mode 100644
index 00000000..5f64aff4
--- /dev/null
+++ b/server/src/scripts/export-catalog.ts
@@ -0,0 +1,145 @@
+/**
+ * export-catalog — build the signed catalog product from the live freeapi DB.
+ *
+ * This is the single source of truth pipeline: every model and its resolved
+ * quirks come straight out of the same SQLite DB the router uses, so the
+ * published catalog can never drift from what the gateway actually serves.
+ * The output JSON is what the standalone catalog server (../../catalog) hands
+ * to clients — fresh ("live") to Premium, a monthly snapshot to free users.
+ *
+ * Usage:
+ * tsx src/scripts/export-catalog.ts [--db <path>] [--out <path>]
+ * [--version <YYYY.MM.DD>] [--tier live|monthly]
+ * [--stdout]
+ *
+ * Defaults: reads the server's data/freeapi.db, writes the suite's
+ * catalog/data/catalog.live.json. The catalog server signs it separately
+ * (catalog/src/scripts/sign-catalog.ts) so the signature covers the exact
+ * bytes served.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { initDb, getDb } from '../db/index.js';
+import { getAllProviders } from '../providers/index.js';
+import { resolveQuirksByModel, quirkKey, listQuirkDefinitions } from '../services/quirks.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SUITE_ROOT = path.resolve(__dirname, '../../../..'); // freeapi/server/src/scripts -> suite root
+
+function arg(name: string): string | undefined {
+ const i = process.argv.indexOf(`--${name}`);
+ return i !== -1 ? process.argv[i + 1] : undefined;
+}
+function flag(name: string): boolean {
+ return process.argv.includes(`--${name}`);
+}
+
+function dateVersion(d = new Date()): string {
+ const yyyy = d.getUTCFullYear();
+ const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+ const dd = String(d.getUTCDate()).padStart(2, '0');
+ return `${yyyy}.${mm}.${dd}`;
+}
+
+interface ModelRow {
+ platform: string;
+ model_id: string;
+ display_name: string;
+ intelligence_rank: number;
+ speed_rank: number;
+ size_label: string;
+ rpm_limit: number | null;
+ rpd_limit: number | null;
+ tpm_limit: number | null;
+ tpd_limit: number | null;
+ monthly_token_budget: string;
+ context_window: number | null;
+ enabled: number;
+ supports_vision: number;
+ supports_tools: number;
+}
+
+function main() {
+ const dbPath = arg('db');
+ const tier = (arg('tier') as 'live' | 'monthly' | undefined) ?? 'live';
+ const version = arg('version') ?? dateVersion();
+
+ initDb(dbPath);
+ const db = getDb();
+
+ const models = db
+ .prepare(
+ `SELECT platform, model_id, display_name, intelligence_rank, speed_rank, size_label,
+ rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window,
+ enabled, supports_vision, supports_tools
+ FROM models
+ ORDER BY intelligence_rank ASC, platform ASC, model_id ASC`,
+ )
+ .all() as ModelRow[];
+
+ const quirksByModel = resolveQuirksByModel(db);
+ const quirkDefs = listQuirkDefinitions(db);
+
+ // Only platforms that actually have a registered provider AND a model in the
+ // catalog — skip 'custom' (user-supplied endpoint, nothing to publish).
+ const livePlatforms = new Set(models.map((m) => m.platform));
+ const platforms = getAllProviders()
+ .filter((p) => p.platform !== 'custom' && livePlatforms.has(p.platform))
+ .map((p) => ({ id: p.platform, name: p.name }))
+ .sort((a, b) => a.id.localeCompare(b.id));
+
+ const catalogModels = models.map((m) => ({
+ platform: m.platform,
+ modelId: m.model_id,
+ displayName: m.display_name,
+ intelligenceRank: m.intelligence_rank,
+ speedRank: m.speed_rank,
+ sizeLabel: m.size_label,
+ limits: {
+ rpm: m.rpm_limit,
+ rpd: m.rpd_limit,
+ tpm: m.tpm_limit,
+ tpd: m.tpd_limit,
+ },
+ monthlyTokenBudget: m.monthly_token_budget,
+ contextWindow: m.context_window,
+ enabled: m.enabled === 1,
+ supportsVision: m.supports_vision === 1,
+ supportsTools: m.supports_tools === 1,
+ quirks: quirksByModel.get(quirkKey(m.platform, m.model_id)) ?? [],
+ }));
+
+ const catalog = {
+ version,
+ generatedAt: new Date().toISOString(),
+ tier,
+ counts: {
+ platforms: platforms.length,
+ models: catalogModels.length,
+ enabledModels: catalogModels.filter((m) => m.enabled).length,
+ quirks: quirkDefs.length,
+ },
+ platforms,
+ models: catalogModels,
+ quirks: quirkDefs,
+ };
+
+ const json = JSON.stringify(catalog, null, 2) + '\n';
+
+ if (flag('stdout')) {
+ process.stdout.write(json);
+ return;
+ }
+
+ const outPath = arg('out') ?? path.join(SUITE_ROOT, 'catalog', 'data', `catalog.${tier}.json`);
+ fs.mkdirSync(path.dirname(outPath), { recursive: true });
+ fs.writeFileSync(outPath, json);
+ console.log(
+ `Wrote ${tier} catalog ${version}: ${catalog.counts.models} models ` +
+ `(${catalog.counts.enabledModels} enabled), ${catalog.counts.platforms} platforms, ` +
+ `${catalog.counts.quirks} quirks -> ${outPath}`,
+ );
+}
+
+main();
diff --git a/server/src/services/catalog-sync.ts b/server/src/services/catalog-sync.ts
new file mode 100644
index 00000000..753d3488
Binary files /dev/null and b/server/src/services/catalog-sync.ts differ
diff --git a/server/src/services/quirks.ts b/server/src/services/quirks.ts
new file mode 100644
index 00000000..2f4706db
Binary files /dev/null and b/server/src/services/quirks.ts differ
diff --git a/shared/types.ts b/shared/types.ts
index d5b8dc4e..b30fc3ba 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -49,6 +49,23 @@ export interface Model {
supportsTools: boolean;
}
+// ---- Quirks ----
+// Structured, reusable notes about catalog models. One quirk is applied to many
+// models via selector parameters (see quirk_targets / services/quirks.ts).
+export type QuirkSeverity = 'info' | 'warning' | 'blocker';
+
+export interface Quirk {
+ slug: string;
+ title: string;
+ body: string;
+ severity: QuirkSeverity;
+}
+
+export interface QuirkTarget {
+ platform: Platform | null;
+ modelGlob: string | null;
+}
+
export interface ModelListRow {
platform: string;
model_id: string;