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

Add catalog controls, persistence backup, and declarative config

Tashfeenf4cd7b4b96b9
diff --git a/.env.example b/.env.example
index be3dcfc0..d240ad31 100644
--- a/.env.example
+++ b/.env.example
@@ -20,6 +20,24 @@ PORT=3001
REQUEST_ANALYTICS_RETENTION_DAYS=90
REQUEST_ANALYTICS_MAX_ROWS=100000
+# Optional SQLite location. Useful on hosts where only one directory is mounted
+# persistently, or when you want to keep the DB outside server/data.
+# FREEAPI_DB_PATH=/app/server/data/freellmapi.db
+
+# Optional encrypted SQLite backup. On startup, FreeLLMAPI restores this backup
+# if the configured DB file is missing; while running, it uploads a fresh backup
+# periodically. File paths and HTTP(S) URLs are supported.
+# FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup
+# FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup
+# FREEAPI_DB_BACKUP_TOKEN=
+# FREEAPI_DB_BACKUP_KEY=use-a-separate-64-char-hex-key-or-omit-to-use-ENCRYPTION_KEY
+# FREEAPI_DB_BACKUP_INTERVAL_MS=300000
+
+# Optional declarative startup config. Use either inline JSON or a path to a JSON
+# file. It is applied idempotently after migrations on every boot.
+# FREEAPI_CONFIG_PATH=/app/server/data/freellmapi.config.json
+# FREEAPI_CONFIG_JSON={"keys":[{"platform":"groq","key":"gsk_...","label":"main"}],"routing":{"strategy":"balanced"}}
+
# Context handoff on model switch. When enabled, FreeLLMAPI injects a compact
# system message into the outbound request whenever a session switches from one
# model to another (e.g. after a fallback). Off by default.
diff --git a/README.md b/README.md
index d5239bc6..c1c1131d 100644
--- a/README.md
+++ b/README.md
@@ -175,6 +175,42 @@ whichever limit prunes first. Set `REQUEST_ANALYTICS_RETENTION_DAYS=0` or
Open http://localhost:5173 (the Vite dev UI), add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.
+### Declarative startup config
+
+For repeatable Docker/server installs, FreeLLMAPI can apply a JSON config on
+every boot. Set `FREEAPI_CONFIG_PATH=/path/to/freellmapi.config.json` or put the
+same JSON in `FREEAPI_CONFIG_JSON`. The config is idempotent: existing keys,
+custom providers, model edits, fallback rows, and routing settings are updated
+instead of duplicated.
+
+```json
+{
+ "keys": [
+ { "platform": "groq", "key": "gsk_...", "label": "main" },
+ { "platform": "google", "key": "AIza...", "enabled": true }
+ ],
+ "customProviders": [
+ {
+ "baseUrl": "http://host.docker.internal:11434/v1",
+ "label": "Ollama",
+ "models": [
+ { "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }
+ ]
+ }
+ ],
+ "models": [
+ {
+ "platform": "groq",
+ "modelId": "llama-3.3-70b-versatile",
+ "displayName": "Llama 3.3 70B",
+ "supportsTools": true,
+ "fallbackEnabled": true
+ }
+ ],
+ "routing": { "strategy": "balanced" }
+}
+```
+
> **Reaching the dev UI from another device on your LAN?** Use `npm run dev:lan` — it passes `--host` through to Vite, which then prints a `Network: http://<your-ip>:5173` URL you can open from a phone or another machine. (Plain `npm run dev -- --host` does *not* work here: the root `dev` script is a `concurrently` wrapper, so the flag never reaches Vite.) API calls go through Vite's dev proxy, so no extra server config is needed.
For a production build without Docker:
@@ -203,7 +239,26 @@ docker compose logs -f freellmapi
By default the container's port is bound to `127.0.0.1` (localhost only). To reach the dashboard/API from another machine on your network, publish it on all interfaces with `HOST_BIND=0.0.0.0 docker compose up -d` — only on a trusted LAN, since the proxy is single-user.
-SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because provider keys are encrypted at rest.
+SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`.
+Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because
+provider keys are encrypted at rest. If your host only persists a specific
+directory, set `FREEAPI_DB_PATH=/that/path/freellmapi.db`.
+
+On hosts with ephemeral disks, configure an encrypted backup target:
+
+```env
+FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup
+# or:
+FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup
+FREEAPI_DB_BACKUP_TOKEN=optional-bearer-token
+FREEAPI_DB_BACKUP_KEY=64-char-hex-backup-key
+FREEAPI_DB_BACKUP_INTERVAL_MS=300000
+```
+
+When the database file is missing at startup, FreeLLMAPI restores the backup
+before migrations run. While the server is running it uploads a fresh encrypted
+backup periodically. If `FREEAPI_DB_BACKUP_KEY` is omitted, the app uses
+`ENCRYPTION_KEY` for the backup envelope too.
More Docker operations and examples live in [docker/README.md](./docker/README.md).
diff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.json
index dafb52a5..4d8960c9 100644
--- a/client/src/i18n/locales/en.json
+++ b/client/src/i18n/locales/en.json
@@ -104,6 +104,15 @@
"providerIdsHeading": "Provider model ids",
"providerIdsHint": "Send the unified model id to fail over across every provider, or a provider-specific id to pin one provider.",
"copyModelName": "Copy model name",
+ "settingsHeading": "Provider settings",
+ "settingsHint": "Local edits to catalog models are kept across catalog syncs. Deleted catalog models stay deleted until you add them again through config.",
+ "catalogModel": "catalog",
+ "customModel": "custom",
+ "localOverride": "local override",
+ "displayName": "Display name",
+ "contextWindow": "Context",
+ "inFallback": "In chain",
+ "saveModelSettings": "Save model settings",
"aggregateBudget": "{count}/mo",
"aggregateBudgetTitle": "Total free tokens per month across this model's providers",
"rateRpm": "{count} RPM",
diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsx
index 804f178a..16875532 100644
--- a/client/src/pages/FallbackPage.tsx
+++ b/client/src/pages/FallbackPage.tsx
@@ -54,6 +54,10 @@ export interface FallbackEntry {
contextWindow?: number | null
supportsVision: boolean
supportsTools: boolean
+ source?: 'catalog' | 'custom'
+ keyId?: number | null
+ keyLabel?: string | null
+ hasOverrides?: boolean
keyCount: number
// Logical-model grouping (sent by the server when unify is relevant). Absent
// for ungrouped rows; the UI falls back to a per-row "solo" group then.
diff --git a/client/src/pages/ModelDetailPage.tsx b/client/src/pages/ModelDetailPage.tsx
index 578b9708..1285e270 100644
--- a/client/src/pages/ModelDetailPage.tsx
+++ b/client/src/pages/ModelDetailPage.tsx
@@ -1,8 +1,12 @@
+import { useEffect, useState } from 'react'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { Link, useParams } from 'react-router-dom'
-import { ChevronLeft } from 'lucide-react'
+import { ChevronLeft, Save, Trash2 } from 'lucide-react'
import { useI18n } from '@/i18n'
import { apiFetch } from '@/lib/api'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Switch } from '@/components/ui/switch'
import { CopyButton } from '@/components/copy-button'
import { Tooltip } from '@/components/tooltip'
import { PageHeader } from '@/components/page-header'
@@ -16,6 +20,14 @@ import {
type Row,
} from './FallbackPage'
+type ModelSettingsPatch = {
+ displayName: string
+ contextWindow: number | null
+ supportsVision: boolean
+ supportsTools: boolean
+ fallbackEnabled: boolean
+}
+
// One model's own page: lists every provider that serves it (this model now
// fails over across these providers). Reached from the Models list; replaces the
// old inline group expansion.
@@ -45,6 +57,26 @@ export default function ModelDetailPage() {
apiFetch('/api/fallback', { method: 'PUT', body: JSON.stringify(data) }),
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['fallback'] }),
})
+ const modelPatchMutation = useMutation({
+ mutationFn: ({ modelDbId, patch }: { modelDbId: number; patch: ModelSettingsPatch }) =>
+ apiFetch(`/api/models/${modelDbId}`, {
+ method: 'PATCH',
+ body: JSON.stringify(patch),
+ }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['fallback'] })
+ queryClient.invalidateQueries({ queryKey: ['fallback', 'routing'] })
+ queryClient.invalidateQueries({ queryKey: ['models'] })
+ },
+ })
+ const modelDeleteMutation = useMutation({
+ mutationFn: (modelDbId: number) => apiFetch(`/api/models/${modelDbId}`, { method: 'DELETE' }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['fallback'] })
+ queryClient.invalidateQueries({ queryKey: ['fallback', 'routing'] })
+ queryClient.invalidateQueries({ queryKey: ['models'] })
+ },
+ })
const isManual = (routing?.strategy ?? 'balanced') === 'priority'
const scoreById = new Map((routing?.scores ?? []).map(s => [s.modelDbId, s]))
@@ -123,6 +155,25 @@ export default function ModelDetailPage() {
</table>
</div>
+ <div className="rounded-2xl border bg-card p-4">
+ <div className="mb-3">
+ <h2 className="text-sm font-medium">{t('models.settingsHeading')}</h2>
+ <p className="mt-0.5 text-xs text-muted-foreground">{t('models.settingsHint')}</p>
+ </div>
+ <div className="space-y-3">
+ {members.map(m => (
+ <ProviderSettingsRow
+ key={m.modelDbId}
+ model={m}
+ saving={modelPatchMutation.isPending && modelPatchMutation.variables?.modelDbId === m.modelDbId}
+ deleting={modelDeleteMutation.isPending && modelDeleteMutation.variables === m.modelDbId}
+ onSave={(patch) => modelPatchMutation.mutate({ modelDbId: m.modelDbId, patch })}
+ onDelete={() => modelDeleteMutation.mutate(m.modelDbId)}
+ />
+ ))}
+ </div>
+ </div>
+
{/* The provider-specific model id to send if you want to pin one provider. */}
<div className="rounded-2xl border bg-card p-4">
<h2 className="text-sm font-medium">{t('models.providerIdsHeading')}</h2>
@@ -154,3 +205,137 @@ export default function ModelDetailPage() {
</div>
)
}
+
+function ProviderSettingsRow({
+ model,
+ saving,
+ deleting,
+ onSave,
+ onDelete,
+}: {
+ model: Row
+ saving: boolean
+ deleting: boolean
+ onSave: (patch: ModelSettingsPatch) => void
+ onDelete: () => void
+}) {
+ const { t } = useI18n()
+ const [displayName, setDisplayName] = useState(model.displayName)
+ const [contextWindow, setContextWindow] = useState(model.contextWindow ? String(model.contextWindow) : '')
+ const [supportsVision, setSupportsVision] = useState(model.supportsVision)
+ const [supportsTools, setSupportsTools] = useState(model.supportsTools)
+ const [fallbackEnabled, setFallbackEnabled] = useState(model.enabled)
+ const [confirmDelete, setConfirmDelete] = useState(false)
+
+ useEffect(() => {
+ setDisplayName(model.displayName)
+ setContextWindow(model.contextWindow ? String(model.contextWindow) : '')
+ setSupportsVision(model.supportsVision)
+ setSupportsTools(model.supportsTools)
+ setFallbackEnabled(model.enabled)
+ setConfirmDelete(false)
+ }, [model.modelDbId, model.displayName, model.contextWindow, model.supportsVision, model.supportsTools, model.enabled])
+
+ useEffect(() => {
+ if (!confirmDelete) return
+ const timer = window.setTimeout(() => setConfirmDelete(false), 3000)
+ return () => window.clearTimeout(timer)
+ }, [confirmDelete])
+
+ const parsedContext = contextWindow.trim() === '' ? null : Number(contextWindow)
+ const contextInvalid = parsedContext !== null && (!Number.isInteger(parsedContext) || parsedContext <= 0)
+ const nameInvalid = displayName.trim().length === 0
+ const dirty =
+ displayName.trim() !== model.displayName ||
+ parsedContext !== (model.contextWindow ?? null) ||
+ supportsVision !== model.supportsVision ||
+ supportsTools !== model.supportsTools ||
+ fallbackEnabled !== model.enabled
+ const canSave = dirty && !nameInvalid && !contextInvalid && !saving && !deleting
+ const sourceLabel = model.source === 'custom' ? t('models.customModel') : t('models.catalogModel')
+
+ function save() {
+ if (!canSave) return
+ onSave({
+ displayName: displayName.trim(),
+ contextWindow: parsedContext,
+ supportsVision,
+ supportsTools,
+ fallbackEnabled,
+ })
+ }
+
+ function remove() {
+ if (!confirmDelete) {
+ setConfirmDelete(true)
+ return
+ }
+ onDelete()
+ }
+
+ return (
+ <div className="rounded-xl border bg-background/60 p-3">
+ <div className="mb-3 flex flex-wrap items-center gap-2">
+ <span className="text-xs font-medium">{model.platform}</span>
+ <code className="min-w-0 truncate font-mono text-[11px] text-muted-foreground">{model.modelId}</code>
+ <span className="rounded-full bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">{sourceLabel}</span>
+ {model.hasOverrides && (
+ <span className="rounded-full bg-emerald-600/15 px-1.5 py-0.5 text-[10px] text-emerald-700 dark:text-emerald-400">
+ {t('models.localOverride')}
+ </span>
+ )}
+ </div>
+ <div className="grid gap-3 md:grid-cols-[minmax(12rem,1fr)_8rem_auto_auto_auto_auto] md:items-end">
+ <label className="space-y-1 text-xs text-muted-foreground">
+ <span>{t('models.displayName')}</span>
+ <Input
+ value={displayName}
+ onChange={e => setDisplayName(e.target.value)}
+ aria-invalid={nameInvalid}
+ className="text-sm"
+ />
+ </label>
+ <label className="space-y-1 text-xs text-muted-foreground">
+ <span>{t('models.contextWindow')}</span>
+ <Input
+ type="number"
+ min={1}
+ step={1}
+ value={contextWindow}
+ onChange={e => setContextWindow(e.target.value)}
+ aria-invalid={contextInvalid}
+ className="text-sm tabular-nums"
+ />
+ </label>
+ <label className="flex h-8 items-center gap-2 text-xs">
+ <Switch size="sm" checked={supportsTools} onCheckedChange={setSupportsTools} />
+ <span>{t('models.tools')}</span>
+ </label>
+ <label className="flex h-8 items-center gap-2 text-xs">
+ <Switch size="sm" checked={supportsVision} onCheckedChange={setSupportsVision} />
+ <span>{t('models.vision')}</span>
+ </label>
+ <label className="flex h-8 items-center gap-2 text-xs">
+ <Switch size="sm" checked={fallbackEnabled} onCheckedChange={setFallbackEnabled} />
+ <span>{t('models.inFallback')}</span>
+ </label>
+ <div className="flex items-center justify-end gap-1">
+ <Tooltip text={t('models.saveModelSettings')}>
+ <Button type="button" size="icon-sm" variant="ghost" disabled={!canSave} onClick={save}>
+ <Save className="size-3.5" />
+ </Button>
+ </Tooltip>
+ <Button
+ type="button"
+ size={confirmDelete ? 'xs' : 'icon-sm'}
+ variant="destructive"
+ disabled={saving || deleting}
+ onClick={remove}
+ >
+ {confirmDelete ? t('common.confirm') : <Trash2 className="size-3.5" />}
+ </Button>
+ </div>
+ </div>
+ </div>
+ )
+}
diff --git a/docker/README.md b/docker/README.md
index 5be329e4..b7411666 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -76,9 +76,36 @@ docker compose up -d --build
| --- | --- | --- | --- |
| `ENCRYPTION_KEY` | Yes | None | 64-character hex key used to encrypt provider API keys at rest. Generate it once and keep it stable. |
| `PORT` | No | `3001` | Host port exposed by Docker Compose. The container listens on port 3001. |
+| `FREEAPI_DB_PATH` | No | `/app/server/data/freellmapi.db` | SQLite file path. Set this when your host only persists one mounted directory. |
+| `FREEAPI_DB_BACKUP_PATH` | No | None | Local encrypted backup file. Restored on startup if the DB file is missing, then refreshed while the app runs. |
+| `FREEAPI_DB_BACKUP_URL` | No | None | HTTP(S) encrypted backup target. Startup uses `GET`; periodic backups use `PUT`. |
+| `FREEAPI_DB_BACKUP_TOKEN` | No | None | Optional bearer token for `FREEAPI_DB_BACKUP_URL`. |
+| `FREEAPI_DB_BACKUP_KEY` | No | `ENCRYPTION_KEY` | 64-character hex key for backup encryption. Use a separate stable key if possible. |
+| `FREEAPI_CONFIG_PATH` | No | None | JSON config file applied idempotently after migrations on every boot. |
+| `FREEAPI_CONFIG_JSON` | No | None | Inline JSON config. Takes precedence over `FREEAPI_CONFIG_PATH`. |
The `freellmapi-data` volume stores SQLite data at `/app/server/data`. Keep the same volume and `ENCRYPTION_KEY` when upgrading, otherwise existing encrypted provider keys cannot be decrypted.
+Example `freellmapi.config.json`:
+
+```json
+{
+ "keys": [
+ { "platform": "groq", "key": "gsk_...", "label": "main" }
+ ],
+ "customProviders": [
+ {
+ "baseUrl": "http://host.docker.internal:11434/v1",
+ "label": "Ollama",
+ "models": [
+ { "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }
+ ]
+ }
+ ],
+ "routing": { "strategy": "balanced" }
+}
+```
+
## Published Image
Images are published to GitHub Container Registry:
diff --git a/server/src/__tests__/db/migrate/roundtrip.test.ts b/server/src/__tests__/db/migrate/roundtrip.test.ts
index e2bd473a..481342d8 100644
--- a/server/src/__tests__/db/migrate/roundtrip.test.ts
+++ b/server/src/__tests__/db/migrate/roundtrip.test.ts
@@ -6,6 +6,7 @@ import { up as runLegacyBaseline } from '../../../db/migrations/20260101_000000_
const LEGACY_BASELINE_FILENAME = '20260101_000000_legacy_baseline.ts';
const CUSTOM_PROVIDER_MODALITIES_FILENAME = '20260627_000001_custom_provider_modalities.ts';
+const CATALOG_MODEL_STATE_FILENAME = '20260627_000002_catalog_model_state.ts';
interface SchemaRow {
type: string;
@@ -58,6 +59,7 @@ describe('migration round trip', () => {
expect(getAppliedMigrationNames(db)).toEqual([
LEGACY_BASELINE_FILENAME,
CUSTOM_PROVIDER_MODALITIES_FILENAME,
+ CATALOG_MODEL_STATE_FILENAME,
]);
} finally {
db.close();
diff --git a/server/src/__tests__/lib/config.test.ts b/server/src/__tests__/lib/config.test.ts
index 5bf43189..b434dc3c 100644
--- a/server/src/__tests__/lib/config.test.ts
+++ b/server/src/__tests__/lib/config.test.ts
@@ -1,7 +1,7 @@
import { describe, it, expect, afterEach } from 'vitest';
import { loadConfig } from '../../lib/config.js';
-const ENV_KEYS = ['PORT', 'HOST', 'DASHBOARD_ORIGINS', 'CLIENT_DIST', 'PROXY_RATE_LIMIT_RPM', 'NODE_ENV'];
+const ENV_KEYS = ['PORT', 'HOST', 'FREEAPI_DB_PATH', 'DASHBOARD_ORIGINS', 'CLIENT_DIST', 'PROXY_RATE_LIMIT_RPM', 'NODE_ENV'];
afterEach(() => {
ENV_KEYS.forEach(k => delete process.env[k]);
@@ -12,6 +12,7 @@ describe('loadConfig', () => {
const cfg = loadConfig();
expect(cfg.port).toBe(3001);
expect(cfg.host).toBe('::');
+ expect(cfg.dbPath).toBeNull();
expect(cfg.dashboardOrigins).toEqual([]);
expect(cfg.clientDist).toBeNull();
expect(cfg.proxyRateLimitRpm).toBe(120);
@@ -38,6 +39,11 @@ describe('loadConfig', () => {
expect(cfg.clientDist).toBe('/opt/client/dist');
});
+ it('reads FREEAPI_DB_PATH from env', () => {
+ process.env.FREEAPI_DB_PATH = '/data/freeapi.db';
+ expect(loadConfig().dbPath).toBe('/data/freeapi.db');
+ });
+
it('parses PROXY_RATE_LIMIT_RPM as a number', () => {
process.env.PROXY_RATE_LIMIT_RPM = '60';
expect(loadConfig().proxyRateLimitRpm).toBe(60);
diff --git a/server/src/__tests__/lib/db-backup.test.ts b/server/src/__tests__/lib/db-backup.test.ts
new file mode 100644
index 00000000..2c840772
--- /dev/null
+++ b/server/src/__tests__/lib/db-backup.test.ts
@@ -0,0 +1,54 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { afterEach, describe, expect, it } from 'vitest';
+import { backupDbNow, restoreDbBackupIfNeeded } from '../../lib/db-backup.js';
+
+const ORIGINAL_BACKUP_PATH = process.env.FREEAPI_DB_BACKUP_PATH;
+const ORIGINAL_BACKUP_TARGET = process.env.FREEAPI_DB_BACKUP_TARGET;
+const ORIGINAL_BACKUP_URL = process.env.FREEAPI_DB_BACKUP_URL;
+const ORIGINAL_BACKUP_KEY = process.env.FREEAPI_DB_BACKUP_KEY;
+const ORIGINAL_ENCRYPTION_KEY = process.env.ENCRYPTION_KEY;
+
+function restoreEnv() {
+ if (ORIGINAL_BACKUP_PATH === undefined) delete process.env.FREEAPI_DB_BACKUP_PATH;
+ else process.env.FREEAPI_DB_BACKUP_PATH = ORIGINAL_BACKUP_PATH;
+ if (ORIGINAL_BACKUP_TARGET === undefined) delete process.env.FREEAPI_DB_BACKUP_TARGET;
+ else process.env.FREEAPI_DB_BACKUP_TARGET = ORIGINAL_BACKUP_TARGET;
+ if (ORIGINAL_BACKUP_URL === undefined) delete process.env.FREEAPI_DB_BACKUP_URL;
+ else process.env.FREEAPI_DB_BACKUP_URL = ORIGINAL_BACKUP_URL;
+ if (ORIGINAL_BACKUP_KEY === undefined) delete process.env.FREEAPI_DB_BACKUP_KEY;
+ else process.env.FREEAPI_DB_BACKUP_KEY = ORIGINAL_BACKUP_KEY;
+ if (ORIGINAL_ENCRYPTION_KEY === undefined) delete process.env.ENCRYPTION_KEY;
+ else process.env.ENCRYPTION_KEY = ORIGINAL_ENCRYPTION_KEY;
+}
+
+describe('encrypted SQLite backup', () => {
+ afterEach(() => restoreEnv());
+
+ it('backs up and restores a SQLite file from a configured path', async () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-db-backup-'));
+ const dbPath = path.join(dir, 'freeapi.db');
+ const backupPath = path.join(dir, 'backup.bin');
+ process.env.ENCRYPTION_KEY = 'a'.repeat(64);
+ process.env.FREEAPI_DB_BACKUP_PATH = backupPath;
+
+ const db = new Database(dbPath);
+ db.exec('CREATE TABLE items (name TEXT NOT NULL); INSERT INTO items (name) VALUES (\'survived\')');
+ const backup = await backupDbNow(db, dbPath);
+ db.close();
+
+ expect(backup.ok).toBe(true);
+ expect(fs.existsSync(backupPath)).toBe(true);
+ expect(fs.readFileSync(backupPath).includes(Buffer.from('survived'))).toBe(false);
+
+ fs.rmSync(dbPath);
+ const restore = await restoreDbBackupIfNeeded(dbPath);
+ expect(restore.restored).toBe(true);
+
+ const restored = new Database(dbPath);
+ expect((restored.prepare('SELECT name FROM items').get() as { name: string }).name).toBe('survived');
+ restored.close();
+ });
+});
diff --git a/server/src/__tests__/routes/models-management.test.ts b/server/src/__tests__/routes/models-management.test.ts
new file mode 100644
index 00000000..4eff86a6
--- /dev/null
+++ b/server/src/__tests__/routes/models-management.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb } from '../../db/index.js';
+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';
+
+let dashToken = '';
+
+async function request(app: Express, method: string, path: string, body?: any) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const url = `http://127.0.0.1:${addr.port}${path}`;
+
+ const res = await fetch(url, {
+ method,
+ headers: {
+ ...(body ? { 'Content-Type': 'application/json' } : {}),
+ ...(isGatedApiPath(path) ? { Authorization: `Bearer ${dashToken}` } : {}),
+ },
+ body: body ? JSON.stringify(body) : undefined,
+ });
+
+ const data = await res.json().catch(() => null);
+ server.close();
+ return { status: res.status, body: data };
+}
+
+describe('Model management API', () => {
+ let app: Express;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ dashToken = mintDashboardToken();
+ });
+
+ it('updates catalog model metadata and records durable overrides', async () => {
+ const target = getDb().prepare(`
+ SELECT id FROM models
+ WHERE platform = 'groq' AND key_id IS NULL
+ ORDER BY id LIMIT 1
+ `).get() as { id: number };
+
+ const { status, body } = await request(app, 'PATCH', `/api/models/${target.id}`, {
+ displayName: 'Locally tuned model',
+ supportsTools: true,
+ contextWindow: 123456,
+ fallbackEnabled: false,
+ });
+ expect(status).toBe(200);
+ expect(body.success).toBe(true);
+
+ const row = getDb().prepare(`
+ SELECT m.display_name, m.supports_tools, m.context_window, fc.enabled AS fallback_enabled
+ FROM models m
+ JOIN fallback_config fc ON fc.model_db_id = m.id
+ WHERE m.id = ?
+ `).get(target.id) as { display_name: string; supports_tools: number; context_window: number; fallback_enabled: number };
+ expect(row).toEqual({
+ display_name: 'Locally tuned model',
+ supports_tools: 1,
+ context_window: 123456,
+ fallback_enabled: 0,
+ });
+
+ const override = getDb().prepare('SELECT overrides_json FROM model_overrides WHERE model_id = (SELECT model_id FROM models WHERE id = ?)')
+ .get(target.id) as { overrides_json: string };
+ expect(JSON.parse(override.overrides_json)).toMatchObject({
+ displayName: 'Locally tuned model',
+ supportsTools: true,
+ contextWindow: 123456,
+ });
+
+ const listed = await request(app, 'GET', '/api/models');
+ const item = listed.body.find((m: any) => m.id === target.id);
+ expect(item.hasOverrides).toBe(true);
+ expect(item.fallbackEnabled).toBe(false);
+ });
+
+ it('deletes a catalog model with a tombstone', async () => {
+ const target = getDb().prepare(`
+ SELECT id, platform, model_id FROM models
+ WHERE platform = 'openrouter' AND key_id IS NULL
+ ORDER BY id LIMIT 1
+ `).get() as { id: number; platform: string; model_id: string };
+
+ const { status, body } = await request(app, 'DELETE', `/api/models/${target.id}`);
+ expect(status).toBe(200);
+ expect(body).toEqual({ success: true, tombstoned: true });
+
+ expect(getDb().prepare('SELECT id FROM models WHERE id = ?').get(target.id)).toBeUndefined();
+ expect(getDb().prepare(`
+ SELECT 1 FROM catalog_model_tombstones
+ WHERE kind = 'chat' AND platform = ? AND model_id = ?
+ `).get(target.platform, target.model_id)).toBeDefined();
+ });
+});
diff --git a/server/src/__tests__/services/catalog-sync.test.ts b/server/src/__tests__/services/catalog-sync.test.ts
index e57c7312..a9b3f3c6 100644
--- a/server/src/__tests__/services/catalog-sync.test.ts
+++ b/server/src/__tests__/services/catalog-sync.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeAll } from 'vitest';
import { initDb, getDb, setSetting, getSetting } from '../../db/index.js';
import { applyCatalog, reapplyCachedCatalog, MIN_CATALOG_VERSION } from '../../services/catalog-sync.js';
import { runMigrationsSync } from '../../db/migrate/runner.js';
+import { recordCatalogModelTombstone, upsertModelOverrides } from '../../services/model-state.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
@@ -149,6 +150,53 @@ describe('applyCatalog', () => {
expect(row.enabled).toBe(1);
});
+ it('re-applies local model overrides after catalog metadata refreshes', () => {
+ const models = existingAsCatalogModels().filter((m) => m.modelId !== 'override-model');
+ models.push(baseModel({
+ modelId: 'override-model',
+ displayName: 'Catalog Name',
+ contextWindow: 1000,
+ supportsTools: false,
+ }));
+ applyCatalog(getDb(), catalogOf(models));
+
+ upsertModelOverrides(getDb(), 'groq', 'override-model', {
+ displayName: 'Local Name',
+ contextWindow: 12345,
+ supportsTools: true,
+ });
+
+ const refreshed = existingAsCatalogModels().filter((m) => m.modelId !== 'override-model');
+ refreshed.push(baseModel({
+ modelId: 'override-model',
+ displayName: 'Catalog Name v2',
+ contextWindow: 2000,
+ supportsTools: false,
+ }));
+ applyCatalog(getDb(), catalogOf(refreshed));
+
+ const row = getDb().prepare(`
+ SELECT display_name, context_window, supports_tools
+ FROM models
+ WHERE platform = 'groq' AND model_id = 'override-model'
+ `).get() as { display_name: string; context_window: number; supports_tools: number };
+ expect(row).toEqual({ display_name: 'Local Name', context_window: 12345, supports_tools: 1 });
+ });
+
+ it('keeps user-deleted catalog models deleted across catalog refreshes', () => {
+ const models = existingAsCatalogModels().filter((m) => m.modelId !== 'tombstone-model');
+ models.push(baseModel({ modelId: 'tombstone-model', displayName: 'Tombstone Me' }));
+ applyCatalog(getDb(), catalogOf(models));
+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeDefined();
+
+ recordCatalogModelTombstone(getDb(), 'chat', 'groq', 'tombstone-model');
+ applyCatalog(getDb(), catalogOf(models));
+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeUndefined();
+
+ applyCatalog(getDb(), catalogOf(models));
+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeUndefined();
+ });
+
it('skips models for platforms this binary has no provider for', () => {
const models = existingAsCatalogModels();
models.push(baseModel({ platform: 'some-future-provider', modelId: 'future-model' }));
diff --git a/server/src/__tests__/services/declarative-config.test.ts b/server/src/__tests__/services/declarative-config.test.ts
new file mode 100644
index 00000000..d806c43a
--- /dev/null
+++ b/server/src/__tests__/services/declarative-config.test.ts
@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { applyDeclarativeConfig, applyDeclarativeConfigFromEnv } from '../../services/declarative-config.js';
+import { getRoutingStrategy } from '../../services/router.js';
+
+const ORIGINAL_CONFIG_JSON = process.env.FREEAPI_CONFIG_JSON;
+const ORIGINAL_CONFIG_PATH = process.env.FREEAPI_CONFIG_PATH;
+
+function restoreEnv() {
+ if (ORIGINAL_CONFIG_JSON === undefined) delete process.env.FREEAPI_CONFIG_JSON;
+ else process.env.FREEAPI_CONFIG_JSON = ORIGINAL_CONFIG_JSON;
+ if (ORIGINAL_CONFIG_PATH === undefined) delete process.env.FREEAPI_CONFIG_PATH;
+ else process.env.FREEAPI_CONFIG_PATH = ORIGINAL_CONFIG_PATH;
+}
+
+describe('declarative config import', () => {
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ beforeEach(() => {
+ delete process.env.FREEAPI_CONFIG_JSON;
+ delete process.env.FREEAPI_CONFIG_PATH;
+ getDb().prepare('DELETE FROM api_keys').run();
+ });
+
+ afterEach(() => restoreEnv());
+
+ it('applies keys, custom providers, model overrides, fallback order and routing', () => {
+ const target = getDb().prepare(`
+ SELECT platform, model_id FROM models
+ WHERE platform = 'groq' AND key_id IS NULL
+ ORDER BY id LIMIT 1
+ `).get() as { platform: string; model_id: string };
+
+ const result = applyDeclarativeConfig({
+ keys: [{ platform: 'groq', key: 'gsk_config_key', label: 'config' }],
+ customProviders: [{
+ baseUrl: 'http://127.0.0.1:9123/v1',
+ apiKey: 'local-key',
+ label: 'Local config',
+ models: [{ model: 'local-chat', displayName: 'Local Chat', supportsTools: true, contextWindow: 32000 }],
+ }],
+ models: [{
+ platform: target.platform,
+ modelId: target.model_id,
+ displayName: 'Config Display',
+ supportsTools: true,
+ contextWindow: 654321,
+ }],
+ fallback: [{ platform: target.platform, modelId: target.model_id, priority: 1, enabled: false }],
+ routing: { strategy: 'custom', weights: { reliability: 3, speed: 1, intelligence: 2 } },
+ });
+
+ expect(result).toMatchObject({ applied: true, keys: 1, customModels: 1, models: 1, fallback: 1, routing: true });
+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'groq'").get() as { n: number }).n).toBe(1);
+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'custom'").get() as { n: number }).n).toBe(1);
+ expect(getDb().prepare(`
+ SELECT display_name, supports_tools, context_window FROM models
+ WHERE platform = 'custom' AND model_id = 'local-chat'
+ `).get()).toEqual({ display_name: 'Local Chat', supports_tools: 1, context_window: 32000 });
+
+ const model = getDb().prepare(`
+ SELECT m.display_name, m.supports_tools, m.context_window, fc.priority, fc.enabled AS fallback_enabled
+ FROM models m
+ JOIN fallback_config fc ON fc.model_db_id = m.id
+ WHERE m.platform = ? AND m.model_id = ?
+ `).get(target.platform, target.model_id) as {
+ display_name: string;
+ supports_tools: number;
+ context_window: number;
+ priority: number;
+ fallback_enabled: number;
+ };
+ expect(model).toEqual({
+ display_name: 'Config Display',
+ supports_tools: 1,
+ context_window: 654321,
+ priority: 1,
+ fallback_enabled: 0,
+ });
+ expect(getDb().prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')
+ .get(target.platform, target.model_id)).toBeDefined();
+ expect(getRoutingStrategy()).toBe('custom');
+
+ applyDeclarativeConfig({
+ models: [{ platform: target.platform, modelId: target.model_id, displayName: 'Edited Again' }],
+ });
+ expect((getDb().prepare(`
+ SELECT fc.enabled AS fallback_enabled
+ FROM models m
+ JOIN fallback_config fc ON fc.model_db_id = m.id
+ WHERE m.platform = ? AND m.model_id = ?
+ `).get(target.platform, target.model_id) as { fallback_enabled: number }).fallback_enabled).toBe(0);
+ });
+
+ it('applies inline JSON from FREEAPI_CONFIG_JSON idempotently', () => {
+ process.env.FREEAPI_CONFIG_JSON = JSON.stringify({
+ keys: [{ platform: 'groq', key: 'gsk_config_key', label: 'config' }],
+ });
+
+ expect(applyDeclarativeConfigFromEnv().applied).toBe(true);
+ expect(applyDeclarativeConfigFromEnv().applied).toBe(true);
+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'groq' AND label = 'config'").get() as { n: number }).n).toBe(1);
+ });
+});
diff --git a/server/src/db/index.ts b/server/src/db/index.ts
index 1bdb6117..bfa7dae9 100644
--- a/server/src/db/index.ts
+++ b/server/src/db/index.ts
@@ -18,6 +18,10 @@ export function getDb(): Database.Database {
return db;
}
+export function getDefaultDbPath(): string {
+ return process.env.FREEAPI_DB_PATH?.trim() || DB_PATH;
+}
+
export function connectDb(
dbPath?: string,
opts?: {
@@ -26,7 +30,7 @@ export function connectDb(
ensureDir?: boolean;
},
): Database.Database {
- const resolvedPath = dbPath ?? DB_PATH;
+ const resolvedPath = dbPath ?? getDefaultDbPath();
const isMemory = resolvedPath === ':memory:';
const ensureDir = opts?.ensureDir ?? true;
diff --git a/server/src/db/migrate/defaults.ts b/server/src/db/migrate/defaults.ts
index 52f7909b..41bdbc15 100644
--- a/server/src/db/migrate/defaults.ts
+++ b/server/src/db/migrate/defaults.ts
@@ -1,6 +1,7 @@
import type Database from 'better-sqlite3';
import * as legacyBaseline from '../migrations/20260101_000000_legacy_baseline.js';
import * as customProviderModalities from '../migrations/20260627_000001_custom_provider_modalities.js';
+import * as catalogModelState from '../migrations/20260627_000002_catalog_model_state.js';
export interface MigrationModule {
up(db: Database.Database): void;
@@ -14,8 +15,10 @@ export interface DefaultMigration {
export const LEGACY_BASELINE_FILENAME = '20260101_000000_legacy_baseline.ts';
export const CUSTOM_PROVIDER_MODALITIES_FILENAME = '20260627_000001_custom_provider_modalities.ts';
+export const CATALOG_MODEL_STATE_FILENAME = '20260627_000002_catalog_model_state.ts';
export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [
{ filename: LEGACY_BASELINE_FILENAME, module: legacyBaseline },
{ filename: CUSTOM_PROVIDER_MODALITIES_FILENAME, module: customProviderModalities },
+ { filename: CATALOG_MODEL_STATE_FILENAME, module: catalogModelState },
];
diff --git a/server/src/db/migrations/20260627_000002_catalog_model_state.ts b/server/src/db/migrations/20260627_000002_catalog_model_state.ts
new file mode 100644
index 00000000..936bd4ad
--- /dev/null
+++ b/server/src/db/migrations/20260627_000002_catalog_model_state.ts
@@ -0,0 +1,32 @@
+import type Database from 'better-sqlite3';
+
+export function up(db: Database.Database): void {
+ db.exec(`
+ CREATE TABLE IF NOT EXISTS catalog_model_tombstones (
+ kind TEXT NOT NULL DEFAULT 'chat',
+ platform TEXT NOT NULL,
+ model_id TEXT NOT NULL,
+ created_at TEXT NOT NULL DEFAULT (datetime('now')),
+ PRIMARY KEY (kind, platform, model_id)
+ );
+
+ CREATE TABLE IF NOT EXISTS model_overrides (
+ platform TEXT NOT NULL,
+ model_id TEXT NOT NULL,
+ overrides_json TEXT NOT NULL DEFAULT '{}',
+ updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+ PRIMARY KEY (platform, model_id)
+ );
+
+ CREATE INDEX IF NOT EXISTS idx_catalog_model_tombstones_platform_model
+ ON catalog_model_tombstones(platform, model_id);
+ `);
+}
+
+export function down(db: Database.Database): void {
+ db.exec(`
+ DROP INDEX IF EXISTS idx_catalog_model_tombstones_platform_model;
+ DROP TABLE IF EXISTS model_overrides;
+ DROP TABLE IF EXISTS catalog_model_tombstones;
+ `);
+}
diff --git a/server/src/index.ts b/server/src/index.ts
index 832512a0..6983535a 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -1,12 +1,14 @@
import './env.js';
import { createApp } from './app.js';
-import { initDb, getSetting } from './db/index.js';
+import { initDb, getDb, getSetting } from './db/index.js';
import { startHealthChecker } from './services/health.js';
import { applyProxyUrl, applyProxyEnabled, applyProxyBypass } from './lib/proxy.js';
import { startCatalogSync } from './services/catalog-sync.js';
import { installProcessSafetyNet } from './lib/process-safety-net.js';
import { NodeScheduler } from './lib/scheduler.js';
import { loadConfig } from './lib/config.js';
+import { applyDeclarativeConfigFromEnv } from './services/declarative-config.js';
+import { restoreDbBackupIfNeeded, startDbBackupPump } from './lib/db-backup.js';
async function main() {
const config = loadConfig();
@@ -18,7 +20,13 @@ async function main() {
const scheduler = new NodeScheduler();
- initDb();
+ if (config.dbPath) {
+ await restoreDbBackupIfNeeded(config.dbPath);
+ } else {
+ await restoreDbBackupIfNeeded();
+ }
+ initDb(config.dbPath ?? undefined);
+ applyDeclarativeConfigFromEnv();
// Load the persisted proxy settings from the DB (env var wins if set).
// Must happen after initDb so the settings table is ready.
@@ -34,6 +42,7 @@ async function main() {
console.log(`Proxy endpoint: http://${display}:${PORT}/v1/chat/completions`);
startHealthChecker(scheduler);
startCatalogSync(scheduler);
+ startDbBackupPump(getDb(), scheduler, config.dbPath ?? undefined);
};
const server = app.listen(Number(PORT), HOST, onReady(HOST));
diff --git a/server/src/lib/config.ts b/server/src/lib/config.ts
index efb0828c..63a6ce40 100644
--- a/server/src/lib/config.ts
+++ b/server/src/lib/config.ts
@@ -11,6 +11,7 @@ function parseRateLimitRpm(): number {
export interface Config {
port: number | string;
host: string;
+ dbPath: string | null;
dashboardOrigins: string[];
clientDist: string | null;
proxyRateLimitRpm: number;
@@ -25,6 +26,7 @@ export function loadConfig(): Config {
// and IPv6 (e.g. IPv6-enabled Docker networks — #180). Hosts with IPv6
// disabled fall back to IPv4-only below; HOST overrides the default outright.
host: process.env.HOST ?? '::',
+ dbPath: process.env.FREEAPI_DB_PATH?.trim() || null,
dashboardOrigins: (process.env.DASHBOARD_ORIGINS ?? '')
.split(',')
.map(s => s.trim())
diff --git a/server/src/lib/db-backup.ts b/server/src/lib/db-backup.ts
new file mode 100644
index 00000000..f64603d1
--- /dev/null
+++ b/server/src/lib/db-backup.ts
@@ -0,0 +1,164 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { gzipSync, gunzipSync } from 'zlib';
+import type Database from 'better-sqlite3';
+import type { Scheduler } from './scheduler.js';
+import { getDefaultDbPath } from '../db/index.js';
+
+const MAGIC = Buffer.from('FAPIBK1\0');
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 30 * 1000;
+const PLACEHOLDER_KEY = 'replace-with-64-char-hex';
+
+export interface DbBackupResult {
+ ok: boolean;
+ target?: string;
+ bytes?: number;
+ restored?: boolean;
+ skipped?: string;
+}
+
+function backupTarget(): string | null {
+ const raw = process.env.FREEAPI_DB_BACKUP_TARGET
+ ?? process.env.FREEAPI_DB_BACKUP_URL
+ ?? process.env.FREEAPI_DB_BACKUP_PATH
+ ?? '';
+ const trimmed = raw.trim();
+ return trimmed.length > 0 ? trimmed : null;
+}
+
+export function isDbBackupConfigured(): boolean {
+ return backupTarget() !== null;
+}
+
+function backupIntervalMs(): number {
+ const raw = process.env.FREEAPI_DB_BACKUP_INTERVAL_MS;
+ if (!raw) return DEFAULT_INTERVAL_MS;
+ const n = Number(raw);
+ return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_INTERVAL_MS;
+}
+
+function isHttpTarget(target: string): boolean {
+ return target.startsWith('https://') || target.startsWith('http://');
+}
+
+function parseBackupKey(): Buffer {
+ const raw = (process.env.FREEAPI_DB_BACKUP_KEY || process.env.ENCRYPTION_KEY || '').trim();
+ if (!raw || raw === PLACEHOLDER_KEY || !/^[0-9a-fA-F]{64}$/.test(raw)) {
+ throw new Error('FREEAPI_DB_BACKUP_KEY or ENCRYPTION_KEY must be a 64-character hex key when DB backup is enabled');
+ }
+ return Buffer.from(raw, 'hex');
+}
+
+function encryptBackup(plain: Buffer): Buffer {
+ const key = parseBackupKey();
+ const iv = crypto.randomBytes(12);
+ const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+ const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]);
+ const tag = cipher.getAuthTag();
+ return Buffer.concat([MAGIC, iv, tag, ciphertext]);
+}
+
+function decryptBackup(payload: Buffer): Buffer {
+ if (payload.length < MAGIC.length + 12 + 16 || !payload.subarray(0, MAGIC.length).equals(MAGIC)) {
+ throw new Error('backup payload has an unsupported format');
+ }
+ const key = parseBackupKey();
+ const ivStart = MAGIC.length;
+ const tagStart = ivStart + 12;
+ const bodyStart = tagStart + 16;
+ const iv = payload.subarray(ivStart, tagStart);
+ const tag = payload.subarray(tagStart, bodyStart);
+ const ciphertext = payload.subarray(bodyStart);
+ const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+ decipher.setAuthTag(tag);
+ return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+async function readTarget(target: string): Promise<Buffer | null> {
+ if (isHttpTarget(target)) {
+ const headers: Record<string, string> = {};
+ const token = process.env.FREEAPI_DB_BACKUP_TOKEN?.trim();
+ if (token) headers.Authorization = `Bearer ${token}`;
+ const res = await fetch(target, { method: 'GET', headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+ if (res.status === 404 || res.status === 204) return null;
+ if (!res.ok) throw new Error(`backup restore failed: HTTP ${res.status}`);
+ return Buffer.from(await res.arrayBuffer());
+ }
+
+ if (!fs.existsSync(target)) return null;
+ return fs.readFileSync(target);
+}
+
+async function writeTarget(target: string, payload: Buffer): Promise<void> {
+ if (isHttpTarget(target)) {
+ const headers: Record<string, string> = { 'Content-Type': 'application/octet-stream' };
+ const token = process.env.FREEAPI_DB_BACKUP_TOKEN?.trim();
+ if (token) headers.Authorization = `Bearer ${token}`;
+ const res = await fetch(target, {
+ method: 'PUT',
+ headers,
+ body: payload,
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+ });
+ if (!res.ok) throw new Error(`backup upload failed: HTTP ${res.status}`);
+ return;
+ }
+
+ fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+ fs.writeFileSync(target, payload);
+}
+
+export async function restoreDbBackupIfNeeded(dbPath = getDefaultDbPath()): Promise<DbBackupResult> {
+ const target = backupTarget();
+ if (!target) return { ok: true, skipped: 'not configured' };
+ if (dbPath === ':memory:') return { ok: true, target, skipped: 'memory database' };
+ if (fs.existsSync(dbPath) && fs.statSync(dbPath).size > 0) return { ok: true, target, skipped: 'database already exists' };
+
+ const payload = await readTarget(target);
+ if (!payload || payload.length === 0) return { ok: true, target, skipped: 'no backup found' };
+
+ let restored: Buffer;
+ try {
+ restored = gunzipSync(decryptBackup(payload));
+ } catch (err) {
+ const detail = err instanceof Error ? err.message : String(err);
+ throw new Error(`could not restore SQLite backup from ${target}: ${detail}`);
+ }
+
+ fs.mkdirSync(path.dirname(path.resolve(dbPath)), { recursive: true });
+ fs.writeFileSync(dbPath, restored);
+ console.log(`[db-backup] restored ${restored.length} bytes from ${target}`);
+ return { ok: true, target, bytes: restored.length, restored: true };
+}
+
+export async function backupDbNow(db: Database.Database, dbPath = getDefaultDbPath()): Promise<DbBackupResult> {
+ const target = backupTarget();
+ if (!target) return { ok: true, skipped: 'not configured' };
+ if (dbPath === ':memory:') return { ok: true, target, skipped: 'memory database' };
+ if (!fs.existsSync(dbPath)) return { ok: false, target, skipped: 'database file missing' };
+
+ try {
+ db.pragma('wal_checkpoint(TRUNCATE)');
+ } catch {
+ // Best effort: reading the main DB still works for rollback-journal or quiet WAL DBs.
+ }
+
+ const plain = fs.readFileSync(dbPath);
+ const payload = encryptBackup(gzipSync(plain));
+ await writeTarget(target, payload);
+ console.log(`[db-backup] uploaded ${plain.length} bytes to ${target}`);
+ return { ok: true, target, bytes: plain.length };
+}
+
+export function startDbBackupPump(db: Database.Database, scheduler: Scheduler, dbPath = getDefaultDbPath()): (() => void) | null {
+ if (!backupTarget()) return null;
+ const run = () => {
+ void backupDbNow(db, dbPath).catch(err => {
+ console.warn(`[db-backup] ${err instanceof Error ? err.message : err}`);
+ });
+ };
+ run();
+ return scheduler.every(backupIntervalMs(), run);
+}
diff --git a/server/src/routes/fallback.ts b/server/src/routes/fallback.ts
index 3bc4643f..c6065894 100644
--- a/server/src/routes/fallback.ts
+++ b/server/src/routes/fallback.ts
@@ -63,9 +63,13 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.speed_rank, m.size_label, m.rpm_limit, m.rpd_limit,
m.tpm_limit, m.tpd_limit, m.context_window,
- m.monthly_token_budget, m.supports_vision, m.supports_tools
+ m.monthly_token_budget, m.supports_vision, m.supports_tools,
+ m.key_id, ak.label AS key_label,
+ mo.overrides_json IS NOT NULL AS has_overrides
FROM fallback_config fc
JOIN models m ON m.id = fc.model_db_id
+ LEFT JOIN api_keys ak ON ak.id = m.key_id
+ LEFT JOIN model_overrides mo ON mo.platform = m.platform AND mo.model_id = m.model_id
WHERE m.enabled = 1
ORDER BY fc.priority ASC
`).all() as any[];
@@ -124,6 +128,10 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {
monthlyTokenBudgetTokens: parseBudget(r.monthly_token_budget),
supportsVision: r.supports_vision === 1,
supportsTools: r.supports_tools === 1,
+ source: r.platform === 'custom' || r.key_id != null ? 'custom' : 'catalog',
+ keyId: r.key_id ?? null,
+ keyLabel: r.key_label ?? null,
+ hasOverrides: Boolean(r.has_overrides),
keyCount: keyCountMap.get(r.platform) ?? 0,
};
}));
diff --git a/server/src/routes/models.ts b/server/src/routes/models.ts
index e92f7045..9dc79d3e 100644
--- a/server/src/routes/models.ts
+++ b/server/src/routes/models.ts
@@ -1,11 +1,69 @@
import { Router } from 'express';
import type { Request, Response } from 'express';
+import { z } from 'zod';
import { getDb } from '../db/index.js';
import { hasProvider } from '../providers/index.js';
import { deleteUnusedCustomEndpointKey } from '../lib/custom-provider-cleanup.js';
+import {
+ isCatalogManagedModel,
+ recordCatalogModelTombstone,
+ upsertModelOverrides,
+ type ModelOverridePatch,
+} from '../services/model-state.js';
export const modelsRouter = Router();
+const modelUpdateSchema = z.object({
+ displayName: z.string().min(1).max(200).optional(),
+ intelligenceRank: z.number().int().min(1).max(1000).optional(),
+ speedRank: z.number().int().min(1).max(1000).optional(),
+ sizeLabel: z.string().min(1).max(40).optional(),
+ rpmLimit: z.number().int().positive().nullable().optional(),
+ rpdLimit: z.number().int().positive().nullable().optional(),
+ tpmLimit: z.number().int().positive().nullable().optional(),
+ tpdLimit: z.number().int().positive().nullable().optional(),
+ monthlyTokenBudget: z.string().max(80).optional(),
+ contextWindow: z.number().int().positive().nullable().optional(),
+ enabled: z.boolean().optional(),
+ supportsVision: z.boolean().optional(),
+ supportsTools: z.boolean().optional(),
+ fallbackEnabled: z.boolean().optional(),
+}).strict();
+
+const MODEL_FIELD_COLUMNS: Record<keyof ModelOverridePatch | 'enabled', string> = {
+ displayName: 'display_name',
+ intelligenceRank: 'intelligence_rank',
+ speedRank: 'speed_rank',
+ sizeLabel: 'size_label',
+ rpmLimit: 'rpm_limit',
+ rpdLimit: 'rpd_limit',
+ tpmLimit: 'tpm_limit',
+ tpdLimit: 'tpd_limit',
+ monthlyTokenBudget: 'monthly_token_budget',
+ contextWindow: 'context_window',
+ supportsVision: 'supports_vision',
+ supportsTools: 'supports_tools',
+ enabled: 'enabled',
+};
+
+type ModelRow = {
+ id: number;
+ platform: string;
+ model_id: string;
+ key_id: number | null;
+};
+
+function dbValue(key: keyof typeof MODEL_FIELD_COLUMNS, value: unknown): unknown {
+ if (key === 'enabled' || key === 'supportsVision' || key === 'supportsTools') return value ? 1 : 0;
+ return value;
+}
+
+function fetchModelRow(id: number): ModelRow | undefined {
+ return getDb()
+ .prepare('SELECT id, platform, model_id, key_id FROM models WHERE id = ?')
+ .get(id) as ModelRow | undefined;
+}
+
modelsRouter.delete('/custom/:id', (req: Request, res: Response) => {
const id = Number(req.params.id);
if (!Number.isInteger(id)) {
@@ -29,13 +87,108 @@ modelsRouter.delete('/custom/:id', (req: Request, res: Response) => {
res.json({ success: true });
});
+modelsRouter.patch('/:id', (req: Request, res: Response) => {
+ const id = Number(req.params.id);
+ if (!Number.isInteger(id)) {
+ res.status(400).json({ error: { message: 'Invalid id' } });
+ return;
+ }
+
+ const parsed = modelUpdateSchema.safeParse(req.body);
+ if (!parsed.success) {
+ res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
+ return;
+ }
+
+ const db = getDb();
+ const row = fetchModelRow(id);
+ if (!row) {
+ res.status(404).json({ error: { message: `Unknown model ${id}` } });
+ return;
+ }
+
+ const modelPatch: Partial<typeof parsed.data> = { ...parsed.data };
+ delete modelPatch.fallbackEnabled;
+ const modelKeys = Object.keys(modelPatch) as Array<keyof typeof modelPatch>;
+ if (modelKeys.length === 0 && parsed.data.fallbackEnabled === undefined) {
+ res.status(400).json({ error: { message: 'No model fields provided' } });
+ return;
+ }
+
+ const applyUpdate = db.transaction(() => {
+ if (modelKeys.length > 0) {
+ const assignments: string[] = [];
+ const values: unknown[] = [];
+ for (const key of modelKeys) {
+ assignments.push(`${MODEL_FIELD_COLUMNS[key as keyof typeof MODEL_FIELD_COLUMNS]} = ?`);
+ values.push(dbValue(key as keyof typeof MODEL_FIELD_COLUMNS, modelPatch[key]));
+ }
+ values.push(id);
+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE id = ?`).run(...values);
+
+ if (isCatalogManagedModel(row)) {
+ const overridePatch: ModelOverridePatch = {};
+ for (const key of [
+ 'displayName', 'intelligenceRank', 'speedRank', 'sizeLabel',
+ 'rpmLimit', 'rpdLimit', 'tpmLimit', 'tpdLimit',
+ 'monthlyTokenBudget', 'contextWindow', 'supportsVision', 'supportsTools',
+ ] as const) {
+ if (Object.prototype.hasOwnProperty.call(modelPatch, key)) {
+ overridePatch[key] = modelPatch[key] as never;
+ }
+ }
+ upsertModelOverrides(db, row.platform, row.model_id, overridePatch);
+ }
+ }
+
+ if (parsed.data.fallbackEnabled !== undefined) {
+ db.prepare('UPDATE fallback_config SET enabled = ? WHERE model_db_id = ?')
+ .run(parsed.data.fallbackEnabled ? 1 : 0, id);
+ }
+ });
+ applyUpdate();
+
+ res.json({ success: true, id });
+});
+
+modelsRouter.delete('/:id', (req: Request, res: Response) => {
+ const id = Number(req.params.id);
+ if (!Number.isInteger(id)) {
+ res.status(400).json({ error: { message: 'Invalid id' } });
+ return;
+ }
+
+ const db = getDb();
+ const row = fetchModelRow(id);
+ if (!row) {
+ res.status(404).json({ error: { message: `Unknown model ${id}` } });
+ return;
+ }
+
+ const remove = db.transaction(() => {
+ if (isCatalogManagedModel(row)) {
+ recordCatalogModelTombstone(db, 'chat', row.platform, row.model_id);
+ }
+ db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?').run(id);
+ db.prepare('DELETE FROM models WHERE id = ?').run(id);
+ if (row.platform === 'custom') deleteUnusedCustomEndpointKey(db, row.key_id);
+ });
+ remove();
+
+ res.json({ success: true, tombstoned: isCatalogManagedModel(row) });
+});
+
// List all models with availability info
modelsRouter.get('/', (_req: Request, res: Response) => {
const db = getDb();
const models = db.prepare(`
- SELECT m.*, fc.priority, fc.enabled as fallback_enabled
+ SELECT m.*, fc.priority, fc.enabled as fallback_enabled,
+ mo.overrides_json IS NOT NULL AS has_overrides,
+ ak.label AS key_label
FROM models m
LEFT JOIN fallback_config fc ON fc.model_db_id = m.id
+ LEFT JOIN model_overrides mo ON mo.platform = m.platform AND mo.model_id = m.model_id
+ LEFT JOIN api_keys ak ON ak.id = m.key_id
ORDER BY COALESCE(fc.priority, m.intelligence_rank) ASC
`).all() as any[];
@@ -68,6 +221,10 @@ modelsRouter.get('/', (_req: Request, res: Response) => {
supportsTools: m.supports_tools === 1,
priority: m.priority,
fallbackEnabled: m.fallback_enabled === 1,
+ source: m.platform === 'custom' || m.key_id != null ? 'custom' : 'catalog',
+ keyId: m.key_id ?? null,
+ keyLabel: m.key_label ?? null,
+ hasOverrides: Boolean(m.has_overrides),
hasProvider: hasProvider(m.platform),
keyCount: keyCountMap.get(m.platform) ?? 0,
}));
diff --git a/server/src/services/catalog-sync.ts b/server/src/services/catalog-sync.ts
index 4f3eab97..1fa3f8f3 100644
--- a/server/src/services/catalog-sync.ts
+++ b/server/src/services/catalog-sync.ts
@@ -5,6 +5,12 @@ import { hasProvider } from '../providers/index.js';
import { MEDIA_PLATFORMS } from './media.js';
import type { Platform } from '@freellmapi/shared/types.js';
import type { Scheduler } from '../lib/scheduler.js';
+import {
+ applyAllModelOverrides,
+ applyModelOverrides,
+ deleteTombstonedCatalogModels,
+ isCatalogModelTombstoned,
+} from './model-state.js';
// Generative-media modalities are routed into the separate media_models table
// (see services/media.ts), never into the chat `models` table.
@@ -144,12 +150,13 @@ function isCatalog(value: unknown): value is Catalog {
* Apply a verified catalog to the local DB inside one transaction.
*
* Rules of engagement with user data:
- * - metadata (name, ranks, limits, context, capabilities) always tracks the
- * catalog — that is the whole point of the product;
+ * - metadata (name, ranks, limits, context, capabilities) tracks the catalog
+ * unless the user has an explicit local override;
* - catalog enabled=false force-disables (the model is dead upstream), but
* enabled=true never re-enables a model the user turned off themselves;
* - models the user added via custom providers (platform='custom' or bound to
* a key) are never touched;
+ * - catalog models the user deleted stay deleted via tombstones;
* - models that vanished from the catalog are deleted, exactly like the
* dead-model migrations do (fallback_config row first, FK order).
*/
@@ -201,6 +208,7 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu
counts.skippedUnknownPlatform++;
continue;
}
+ if (isCatalogModelTombstoned(db, 'media', m.platform, m.modelId)) continue;
inMediaCatalog.add(`${m.platform}:${m.modelId}`);
const mrow = selectMedia.get(m.platform, m.modelId) as { id: number; enabled: number } | undefined;
const mfields = {
@@ -226,6 +234,7 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu
counts.skippedUnknownPlatform++;
continue;
}
+ if (isCatalogModelTombstoned(db, 'chat', m.platform, m.modelId)) continue;
inCatalog.add(`${m.platform}:${m.modelId}`);
const row = selectModel.get(m.platform, m.modelId) as { id: number; enabled: number } | undefined;
@@ -247,13 +256,18 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu
// Catalog disable wins (dead upstream); local disable also wins.
const enabled = m.enabled ? row.enabled : 0;
updateModel.run({ ...fields, id: row.id, enabled });
+ applyModelOverrides(db, m.platform, m.modelId);
counts.updated++;
} else {
insertModel.run({ ...fields, platform: m.platform, modelId: m.modelId, enabled: m.enabled ? 1 : 0 });
+ applyModelOverrides(db, m.platform, m.modelId);
counts.inserted++;
}
}
+ counts.removed += deleteTombstonedCatalogModels(db);
+ applyAllModelOverrides(db);
+
// Ensure every model has a fallback_config row (same invariant migrations keep).
const missingFb = db
.prepare(
@@ -268,7 +282,13 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu
// Remove catalog-managed models that the catalog no longer lists.
const candidates = db
- .prepare(`SELECT id, platform, model_id FROM models WHERE platform != 'custom' AND key_id IS NULL`)
+ .prepare(`
+ SELECT id, platform, model_id
+ FROM models
+ WHERE platform != 'custom'
+ AND key_id IS NULL
+ AND size_label NOT IN ('User', 'Custom')
+ `)
.all() as { id: number; platform: string; model_id: string }[];
const deleteFb = db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?');
const deleteModel = db.prepare('DELETE FROM models WHERE id = ?');
diff --git a/server/src/services/declarative-config.ts b/server/src/services/declarative-config.ts
new file mode 100644
index 00000000..d943c177
--- /dev/null
+++ b/server/src/services/declarative-config.ts
@@ -0,0 +1,391 @@
+import fs from 'fs';
+import { z } from 'zod';
+import type Database from 'better-sqlite3';
+import { getDb } from '../db/index.js';
+import { encrypt } from '../lib/crypto.js';
+import { resolveProvider } from '../providers/index.js';
+import { setCustomWeights, setRoutingStrategy } from './router.js';
+import {
+ clearCatalogModelTombstone,
+ isCatalogManagedModel,
+ upsertModelOverrides,
+ type ModelOverridePatch,
+} from './model-state.js';
+
+const modelEntrySchema = z.union([
+ z.string().min(1),
+ z.object({
+ model: z.string().min(1),
+ displayName: z.string().optional(),
+ intelligenceRank: z.number().int().min(1).max(1000).optional(),
+ speedRank: z.number().int().min(1).max(1000).optional(),
+ sizeLabel: z.string().min(1).max(40).optional(),
+ monthlyTokenBudget: z.string().max(80).optional(),
+ contextWindow: z.number().int().positive().nullable().optional(),
+ supportsVision: z.boolean().optional(),
+ supportsTools: z.boolean().optional(),
+ fallbackEnabled: z.boolean().optional(),
+ }),
+]);
+
+const keySchema = z.object({
+ platform: z.string().min(1),
+ key: z.string().optional(),
+ label: z.string().optional(),
+ baseUrl: z.string().url().optional(),
+ enabled: z.boolean().optional(),
+});
+
+const customProviderSchema = z.object({
+ baseUrl: z.string().url(),
+ apiKey: z.string().optional(),
+ label: z.string().optional(),
+ models: z.array(modelEntrySchema).default([]),
+});
+
+const modelSchema = z.object({
+ platform: z.string().min(1),
+ modelId: z.string().min(1),
+ displayName: z.string().min(1).optional(),
+ intelligenceRank: z.number().int().min(1).max(1000).optional(),
+ speedRank: z.number().int().min(1).max(1000).optional(),
+ sizeLabel: z.string().min(1).max(40).optional(),
+ rpmLimit: z.number().int().positive().nullable().optional(),
+ rpdLimit: z.number().int().positive().nullable().optional(),
+ tpmLimit: z.number().int().positive().nullable().optional(),
+ tpdLimit: z.number().int().positive().nullable().optional(),
+ monthlyTokenBudget: z.string().max(80).optional(),
+ contextWindow: z.number().int().positive().nullable().optional(),
+ enabled: z.boolean().optional(),
+ supportsVision: z.boolean().optional(),
+ supportsTools: z.boolean().optional(),
+ fallbackEnabled: z.boolean().optional(),
+});
+
+const fallbackEntrySchema = z.object({
+ platform: z.string().min(1),
+ modelId: z.string().min(1),
+ priority: z.number().int().positive().optional(),
+ enabled: z.boolean().optional(),
+});
+
+const declarativeConfigSchema = z.object({
+ keys: z.array(keySchema).optional(),
+ customProviders: z.array(customProviderSchema).optional(),
+ models: z.array(modelSchema).optional(),
+ fallback: z.array(fallbackEntrySchema).optional(),
+ routing: z.object({
+ strategy: z.enum(['priority', 'balanced', 'smartest', 'fastest', 'reliable', 'custom']),
+ weights: z.object({
+ reliability: z.number().nonnegative(),
+ speed: z.number().nonnegative(),
+ intelligence: z.number().nonnegative(),
+ }).optional(),
+ }).optional(),
+}).strict();
+
+export type DeclarativeConfig = z.infer<typeof declarativeConfigSchema>;
+
+export interface DeclarativeConfigResult {
+ applied: boolean;
+ source?: string;
+ keys: number;
+ customModels: number;
+ models: number;
+ fallback: number;
+ routing: boolean;
+}
+
+interface NormalizedCustomModel {
+ modelId: string;
+ displayName: string;
+ intelligenceRank?: number;
+ speedRank?: number;
+ sizeLabel?: string;
+ monthlyTokenBudget?: string;
+ contextWindow?: number | null;
+ supportsVision?: boolean;
+ supportsTools?: boolean;
+ fallbackEnabled?: boolean;
+}
+
+function readConfigFromEnv(): { source: string; value: unknown } | null {
+ const inline = process.env.FREEAPI_CONFIG_JSON?.trim();
+ if (inline) return { source: 'FREEAPI_CONFIG_JSON', value: JSON.parse(inline) };
+
+ const configPath = process.env.FREEAPI_CONFIG_PATH?.trim();
+ if (configPath) return { source: configPath, value: JSON.parse(fs.readFileSync(configPath, 'utf8')) };
+
+ return null;
+}
+
+function encryptedKey(raw: string) {
+ const { encrypted, iv, authTag } = encrypt(raw);
+ return { encrypted, iv, authTag };
+}
+
+function upsertApiKey(db: Database.Database, input: z.infer<typeof keySchema>): number {
+ const platform = input.platform.trim();
+ const enabled = input.enabled === false ? 0 : 1;
+ const isCustom = platform === 'custom';
+ const baseUrl = input.baseUrl?.trim().replace(/\/+$/, '') ?? null;
+ const provider = !isCustom ? resolveProvider(platform as never) : null;
+ if (!isCustom && !provider) throw new Error(`unknown provider platform: ${platform}`);
+ const keyToStore = input.key?.trim() || (provider?.keyless ? 'no-key' : '');
+ if (!keyToStore) throw new Error(`key is required for ${platform}`);
+ const label = input.label?.trim() || (isCustom ? 'Custom' : 'env');
+ const key = encryptedKey(keyToStore);
+
+ if (isCustom) {
+ if (!baseUrl) throw new Error('baseUrl is required for custom keys');
+ const existing = db.prepare("SELECT id FROM api_keys WHERE platform = 'custom' AND base_url = ?").get(baseUrl) as { id: number } | undefined;
+ if (existing) {
+ db.prepare(`
+ UPDATE api_keys
+ SET label = ?, encrypted_key = ?, iv = ?, auth_tag = ?, enabled = ?, status = 'unknown'
+ WHERE id = ?
+ `).run(label, key.encrypted, key.iv, key.authTag, enabled, existing.id);
+ return existing.id;
+ }
+ const inserted = db.prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)
+ VALUES ('custom', ?, ?, ?, ?, 'unknown', ?, ?)
+ `).run(label, key.encrypted, key.iv, key.authTag, enabled, baseUrl);
+ return Number(inserted.lastInsertRowid);
+ }
+
+ const existing = db.prepare('SELECT id FROM api_keys WHERE platform = ? AND label = ? AND base_url IS NULL LIMIT 1')
+ .get(platform, label) as { id: number } | undefined;
+ if (existing) {
+ db.prepare(`
+ UPDATE api_keys
+ SET encrypted_key = ?, iv = ?, auth_tag = ?, enabled = ?, status = 'unknown'
+ WHERE id = ?
+ `).run(key.encrypted, key.iv, key.authTag, enabled, existing.id);
+ return existing.id;
+ }
+ const inserted = db.prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
+ VALUES (?, ?, ?, ?, ?, 'unknown', ?)
+ `).run(platform, label, key.encrypted, key.iv, key.authTag, enabled);
+ return Number(inserted.lastInsertRowid);
+}
+
+function normalizeModelEntry(entry: z.infer<typeof modelEntrySchema>): NormalizedCustomModel {
+ if (typeof entry === 'string') return { modelId: entry.trim(), displayName: entry.trim() };
+ const modelId = entry.model.trim();
+ return { ...entry, modelId, displayName: entry.displayName?.trim() || modelId };
+}
+
+function ensureFallbackRow(db: Database.Database, modelDbId: number, enabled = true, updateExisting = true): void {
+ const existing = db.prepare('SELECT 1 FROM fallback_config WHERE model_db_id = ?').get(modelDbId);
+ if (existing) {
+ if (updateExisting) {
+ db.prepare('UPDATE fallback_config SET enabled = ? WHERE model_db_id = ?').run(enabled ? 1 : 0, modelDbId);
+ }
+ return;
+ }
+ const max = db.prepare('SELECT COALESCE(MAX(priority), 0) AS m FROM fallback_config').get() as { m: number };
+ db.prepare('INSERT INTO fallback_config (model_db_id, priority, enabled) VALUES (?, ?, ?)')
+ .run(modelDbId, max.m + 1, enabled ? 1 : 0);
+}
+
+function registerCustomProvider(db: Database.Database, input: z.infer<typeof customProviderSchema>): number {
+ const keyId = upsertApiKey(db, {
+ platform: 'custom',
+ key: input.apiKey,
+ label: input.label,
+ baseUrl: input.baseUrl,
+ enabled: true,
+ });
+ let registered = 0;
+ for (const entry of input.models) {
+ const model = normalizeModelEntry(entry);
+ db.prepare(`
+ INSERT INTO models
+ (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, key_id)
+ VALUES ('custom', ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, 1, ?, ?, ?)
+ ON CONFLICT(platform, model_id)
+ DO UPDATE SET
+ display_name = excluded.display_name,
+ intelligence_rank = excluded.intelligence_rank,
+ speed_rank = excluded.speed_rank,
+ size_label = excluded.size_label,
+ monthly_token_budget = excluded.monthly_token_budget,
+ context_window = excluded.context_window,
+ supports_vision = excluded.supports_vision,
+ supports_tools = excluded.supports_tools,
+ key_id = excluded.key_id,
+ enabled = 1
+ `).run(
+ model.modelId,
+ model.displayName,
+ model.intelligenceRank ?? 50,
+ model.speedRank ?? 50,
+ model.sizeLabel ?? 'Custom',
+ model.monthlyTokenBudget ?? '',
+ model.contextWindow ?? null,
+ model.supportsVision ? 1 : 0,
+ model.supportsTools ? 1 : 0,
+ keyId,
+ );
+ const row = db.prepare("SELECT id FROM models WHERE platform = 'custom' AND model_id = ?").get(model.modelId) as { id: number };
+ ensureFallbackRow(db, row.id, model.fallbackEnabled !== false);
+ registered++;
+ }
+ return registered;
+}
+
+function modelPatchFromInput(input: z.infer<typeof modelSchema>): ModelOverridePatch {
+ const patch: ModelOverridePatch = {};
+ for (const key of [
+ 'displayName', 'intelligenceRank', 'speedRank', 'sizeLabel',
+ 'rpmLimit', 'rpdLimit', 'tpmLimit', 'tpdLimit',
+ 'monthlyTokenBudget', 'contextWindow', 'supportsVision', 'supportsTools',
+ ] as const) {
+ if (Object.prototype.hasOwnProperty.call(input, key)) patch[key] = input[key] as never;
+ }
+ return patch;
+}
+
+function upsertModel(db: Database.Database, input: z.infer<typeof modelSchema>): void {
+ const platform = input.platform.trim();
+ const modelId = input.modelId.trim();
+ clearCatalogModelTombstone(db, 'chat', platform, modelId);
+ const existing = db.prepare('SELECT id, platform, model_id, key_id FROM models WHERE platform = ? AND model_id = ?')
+ .get(platform, modelId) as { id: number; platform: string; model_id: string; key_id: number | null } | undefined;
+
+ if (!existing) {
+ db.prepare(`
+ INSERT INTO models
+ (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)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ `).run(
+ platform,
+ modelId,
+ input.displayName ?? modelId,
+ input.intelligenceRank ?? 50,
+ input.speedRank ?? 50,
+ input.sizeLabel ?? 'User',
+ input.rpmLimit ?? null,
+ input.rpdLimit ?? null,
+ input.tpmLimit ?? null,
+ input.tpdLimit ?? null,
+ input.monthlyTokenBudget ?? '',
+ input.contextWindow ?? null,
+ input.enabled === false ? 0 : 1,
+ input.supportsVision ? 1 : 0,
+ input.supportsTools ? 1 : 0,
+ );
+ const created = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?').get(platform, modelId) as { id: number };
+ ensureFallbackRow(db, created.id, input.fallbackEnabled ?? input.enabled !== false);
+ return;
+ }
+
+ const patch = modelPatchFromInput(input);
+ const assignments: string[] = [];
+ const values: unknown[] = [];
+ const columnMap: Record<keyof ModelOverridePatch, string> = {
+ displayName: 'display_name',
+ intelligenceRank: 'intelligence_rank',
+ speedRank: 'speed_rank',
+ sizeLabel: 'size_label',
+ rpmLimit: 'rpm_limit',
+ rpdLimit: 'rpd_limit',
+ tpmLimit: 'tpm_limit',
+ tpdLimit: 'tpd_limit',
+ monthlyTokenBudget: 'monthly_token_budget',
+ contextWindow: 'context_window',
+ supportsVision: 'supports_vision',
+ supportsTools: 'supports_tools',
+ };
+ for (const key of Object.keys(patch) as Array<keyof ModelOverridePatch>) {
+ assignments.push(`${columnMap[key]} = ?`);
+ values.push(key === 'supportsVision' || key === 'supportsTools' ? (patch[key] ? 1 : 0) : patch[key]);
+ }
+ if (input.enabled !== undefined) {
+ assignments.push('enabled = ?');
+ values.push(input.enabled ? 1 : 0);
+ }
+ if (assignments.length > 0) {
+ values.push(existing.id);
+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE id = ?`).run(...values);
+ }
+ if (isCatalogManagedModel(existing) && Object.keys(patch).length > 0) {
+ upsertModelOverrides(db, platform, modelId, patch);
+ }
+ ensureFallbackRow(db, existing.id, input.fallbackEnabled ?? input.enabled !== false, input.fallbackEnabled !== undefined);
+}
+
+function applyFallback(db: Database.Database, entries: z.infer<typeof fallbackEntrySchema>[]): number {
+ const update = db.prepare('UPDATE fallback_config SET priority = ?, enabled = ? WHERE model_db_id = ?');
+ let changed = 0;
+ entries.forEach((entry, i) => {
+ const row = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?')
+ .get(entry.platform, entry.modelId) as { id: number } | undefined;
+ if (!row) return;
+ ensureFallbackRow(db, row.id, entry.enabled !== false);
+ update.run(entry.priority ?? i + 1, entry.enabled === false ? 0 : 1, row.id);
+ changed++;
+ });
+ return changed;
+}
+
+export function applyDeclarativeConfig(input: unknown, source = 'inline'): DeclarativeConfigResult {
+ const parsed = declarativeConfigSchema.safeParse(input);
+ if (!parsed.success) {
+ throw new Error(`invalid declarative config: ${parsed.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`);
+ }
+
+ const db = getDb();
+ const result: DeclarativeConfigResult = {
+ applied: true,
+ source,
+ keys: 0,
+ customModels: 0,
+ models: 0,
+ fallback: 0,
+ routing: false,
+ };
+
+ const apply = db.transaction(() => {
+ for (const key of parsed.data.keys ?? []) {
+ upsertApiKey(db, key);
+ result.keys++;
+ }
+ for (const customProvider of parsed.data.customProviders ?? []) {
+ result.customModels += registerCustomProvider(db, customProvider);
+ }
+ for (const model of parsed.data.models ?? []) {
+ upsertModel(db, model);
+ result.models++;
+ }
+ if (parsed.data.fallback) {
+ result.fallback = applyFallback(db, parsed.data.fallback);
+ }
+ if (parsed.data.routing) {
+ if (parsed.data.routing.weights) setCustomWeights(parsed.data.routing.weights);
+ setRoutingStrategy(parsed.data.routing.strategy);
+ result.routing = true;
+ }
+ });
+ apply();
+ return result;
+}
+
+export function applyDeclarativeConfigFromEnv(): DeclarativeConfigResult {
+ const loaded = readConfigFromEnv();
+ if (!loaded) {
+ return { applied: false, keys: 0, customModels: 0, models: 0, fallback: 0, routing: false };
+ }
+ const result = applyDeclarativeConfig(loaded.value, loaded.source);
+ console.log(
+ `[config] applied ${loaded.source}: ${result.keys} keys, ${result.customModels} custom models, ` +
+ `${result.models} model edits, ${result.fallback} fallback rows${result.routing ? ', routing' : ''}`,
+ );
+ return result;
+}
diff --git a/server/src/services/model-state.ts b/server/src/services/model-state.ts
new file mode 100644
index 00000000..9e42e519
--- /dev/null
+++ b/server/src/services/model-state.ts
@@ -0,0 +1,192 @@
+import type Database from 'better-sqlite3';
+
+export type CatalogModelKind = 'chat' | 'media';
+
+export interface ModelOverridePatch {
+ displayName?: string;
+ intelligenceRank?: number;
+ speedRank?: number;
+ sizeLabel?: string;
+ rpmLimit?: number | null;
+ rpdLimit?: number | null;
+ tpmLimit?: number | null;
+ tpdLimit?: number | null;
+ monthlyTokenBudget?: string;
+ contextWindow?: number | null;
+ supportsVision?: boolean;
+ supportsTools?: boolean;
+}
+
+type StoredOverrides = Partial<ModelOverridePatch>;
+
+const OVERRIDE_COLUMNS: Record<keyof ModelOverridePatch, string> = {
+ displayName: 'display_name',
+ intelligenceRank: 'intelligence_rank',
+ speedRank: 'speed_rank',
+ sizeLabel: 'size_label',
+ rpmLimit: 'rpm_limit',
+ rpdLimit: 'rpd_limit',
+ tpmLimit: 'tpm_limit',
+ tpdLimit: 'tpd_limit',
+ monthlyTokenBudget: 'monthly_token_budget',
+ contextWindow: 'context_window',
+ supportsVision: 'supports_vision',
+ supportsTools: 'supports_tools',
+};
+
+function parseOverrides(raw: string | undefined): StoredOverrides {
+ if (!raw) return {};
+ try {
+ const parsed = JSON.parse(raw) as unknown;
+ return parsed && typeof parsed === 'object' ? parsed as StoredOverrides : {};
+ } catch {
+ return {};
+ }
+}
+
+function toDbValue(key: keyof ModelOverridePatch, value: unknown): unknown {
+ if (key === 'supportsVision' || key === 'supportsTools') return value ? 1 : 0;
+ return value;
+}
+
+function cleanPatch(patch: ModelOverridePatch): StoredOverrides {
+ const cleaned: StoredOverrides = {};
+ for (const key of Object.keys(OVERRIDE_COLUMNS) as Array<keyof ModelOverridePatch>) {
+ if (Object.prototype.hasOwnProperty.call(patch, key)) {
+ cleaned[key] = patch[key] as never;
+ }
+ }
+ return cleaned;
+}
+
+export function isCatalogManagedModel(row: { platform: string; key_id?: number | null }): boolean {
+ return row.platform !== 'custom' && row.key_id == null;
+}
+
+export function isCatalogModelTombstoned(
+ db: Database.Database,
+ kind: CatalogModelKind,
+ platform: string,
+ modelId: string,
+): boolean {
+ return !!db
+ .prepare('SELECT 1 FROM catalog_model_tombstones WHERE kind = ? AND platform = ? AND model_id = ?')
+ .get(kind, platform, modelId);
+}
+
+export function recordCatalogModelTombstone(
+ db: Database.Database,
+ kind: CatalogModelKind,
+ platform: string,
+ modelId: string,
+): void {
+ db.prepare(`
+ INSERT INTO catalog_model_tombstones (kind, platform, model_id)
+ VALUES (?, ?, ?)
+ ON CONFLICT(kind, platform, model_id) DO UPDATE SET created_at = datetime('now')
+ `).run(kind, platform, modelId);
+ if (kind === 'chat') {
+ db.prepare('DELETE FROM model_overrides WHERE platform = ? AND model_id = ?').run(platform, modelId);
+ }
+}
+
+export function clearCatalogModelTombstone(
+ db: Database.Database,
+ kind: CatalogModelKind,
+ platform: string,
+ modelId: string,
+): void {
+ db.prepare('DELETE FROM catalog_model_tombstones WHERE kind = ? AND platform = ? AND model_id = ?')
+ .run(kind, platform, modelId);
+}
+
+export function upsertModelOverrides(
+ db: Database.Database,
+ platform: string,
+ modelId: string,
+ patch: ModelOverridePatch,
+): StoredOverrides {
+ const cleaned = cleanPatch(patch);
+ if (Object.keys(cleaned).length === 0) return {};
+ const existing = db
+ .prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')
+ .get(platform, modelId) as { overrides_json: string } | undefined;
+ const merged: StoredOverrides = { ...parseOverrides(existing?.overrides_json), ...cleaned };
+ db.prepare(`
+ INSERT INTO model_overrides (platform, model_id, overrides_json, updated_at)
+ VALUES (?, ?, ?, datetime('now'))
+ ON CONFLICT(platform, model_id)
+ DO UPDATE SET overrides_json = excluded.overrides_json, updated_at = excluded.updated_at
+ `).run(platform, modelId, JSON.stringify(merged));
+ return merged;
+}
+
+export function getModelOverrides(
+ db: Database.Database,
+ platform: string,
+ modelId: string,
+): StoredOverrides {
+ const row = db
+ .prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')
+ .get(platform, modelId) as { overrides_json: string } | undefined;
+ return parseOverrides(row?.overrides_json);
+}
+
+export function applyModelOverrides(
+ db: Database.Database,
+ platform: string,
+ modelId: string,
+): boolean {
+ const overrides = getModelOverrides(db, platform, modelId);
+ const keys = Object.keys(overrides) as Array<keyof ModelOverridePatch>;
+ if (keys.length === 0) return false;
+
+ const assignments: string[] = [];
+ const values: unknown[] = [];
+ for (const key of keys) {
+ assignments.push(`${OVERRIDE_COLUMNS[key]} = ?`);
+ values.push(toDbValue(key, overrides[key]));
+ }
+ values.push(platform, modelId);
+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE platform = ? AND model_id = ?`).run(...values);
+ return true;
+}
+
+export function applyAllModelOverrides(db: Database.Database): number {
+ const rows = db.prepare('SELECT platform, model_id FROM model_overrides').all() as { platform: string; model_id: string }[];
+ let applied = 0;
+ for (const row of rows) {
+ if (applyModelOverrides(db, row.platform, row.model_id)) applied++;
+ }
+ return applied;
+}
+
+export function deleteTombstonedCatalogModels(db: Database.Database): number {
+ const chatRows = db.prepare(`
+ SELECT m.id, m.platform, m.model_id
+ FROM models m
+ JOIN catalog_model_tombstones t
+ ON t.kind = 'chat' AND t.platform = m.platform AND t.model_id = m.model_id
+ WHERE m.platform != 'custom' AND m.key_id IS NULL
+ `).all() as { id: number; platform: string; model_id: string }[];
+ const mediaRows = db.prepare(`
+ SELECT mm.id
+ FROM media_models mm
+ JOIN catalog_model_tombstones t
+ ON t.kind = 'media' AND t.platform = mm.platform AND t.model_id = mm.model_id
+ `).all() as { id: number }[];
+
+ const deleteChatFallback = db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?');
+ const deleteChat = db.prepare('DELETE FROM models WHERE id = ?');
+ const deleteMedia = db.prepare('DELETE FROM media_models WHERE id = ?');
+
+ for (const row of chatRows) {
+ deleteChatFallback.run(row.id);
+ deleteChat.run(row.id);
+ }
+ for (const row of mediaRows) {
+ deleteMedia.run(row.id);
+ }
+
+ return chatRows.length + mediaRows.length;
+}