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(custom): auto-sync custom provider model lists on a schedule (#746)

suantea (asuan_suan)eea2ca9a3722
diff --git a/server/src/__tests__/services/custom-model-sync.test.ts b/server/src/__tests__/services/custom-model-sync.test.ts
new file mode 100644
index 00000000..8f6fa97a
--- /dev/null
+++ b/server/src/__tests__/services/custom-model-sync.test.ts
@@ -0,0 +1,189 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { getDb, initDb } from '../../db/index.js';
+import { runCustomModelSync, customModelSyncIntervalMs, customModelSyncFreePatterns, startCustomModelSync } from '../../services/custom-model-sync.js';
+import { discoverEndpointModels } from '../../services/model-discovery.js';
+import { endpointScopeForBaseUrl } from '../../lib/endpoint-scope.js';
+
+// The sync pass talks to the outside world ONLY through discoverEndpointModels;
+// stub it so each test controls what an endpoint "serves" today.
+vi.mock('../../services/model-discovery.js', async () => {
+ const actual = await vi.importActual('../../services/model-discovery.js');
+ return { ...actual, discoverEndpointModels: vi.fn() };
+});
+
+// Stored custom credentials are decrypted by the crypto module; make it return
+// a stable plaintext so listCustomEndpoints can read back the rows we insert.
+vi.mock('../../lib/crypto.js', async () => {
+ const actual = await vi.importActual('../../lib/crypto.js');
+ return { ...actual, decrypt: vi.fn(() => 'mocked-api-key') };
+});
+
+const ORIGINAL_INTERVAL = process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS;
+
+function addCustomEndpoint(baseUrl: string, label = 'endpoint'): void {
+ getDb().prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)
+ VALUES ('custom', ?, 'enc', 'iv', 'tag', 'healthy', 1, ?)
+ `).run(label, baseUrl);
+}
+
+function addDisabledCustomEndpoint(baseUrl: string, label = 'disabled-endpoint'): void {
+ getDb().prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)
+ VALUES ('custom', ?, 'enc', 'iv', 'tag', 'healthy', 0, ?)
+ `).run(label, baseUrl);
+}
+
+function customModelIds(): string[] {
+ const rows = getDb().prepare("SELECT model_id FROM models WHERE platform = 'custom'").all() as { model_id: string }[];
+ return rows.map(r => r.model_id).sort();
+}
+
+describe('custom model sync', () => {
+ beforeEach(() => {
+ process.env.DEV_MODE = 'true';
+ process.env.NODE_ENV = 'test';
+ initDb(':memory:');
+ // initDb seeds the real catalog; wipe it so each test controls its own rows.
+ getDb().exec('DELETE FROM fallback_config; DELETE FROM api_keys; DELETE FROM models; DELETE FROM requests;');
+ vi.clearAllMocks();
+ });
+
+ afterEach(() => {
+ if (ORIGINAL_INTERVAL === undefined) {
+ delete process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS;
+ } else {
+ process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS = ORIGINAL_INTERVAL;
+ }
+ });
+
+ it('reports zero endpoints when none are configured', async () => {
+ const result = await runCustomModelSync(getDb());
+ expect(result.endpoints).toBe(0);
+ expect(result.added).toBe(0);
+ expect(result.skipped).toBe(0);
+ expect(result.failures).toEqual([]);
+ });
+
+ it('registers newly discovered models for a configured endpoint', async () => {
+ addCustomEndpoint('http://localhost:9999');
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([
+ { id: 'model-a', ownedBy: null },
+ { id: 'model-b', ownedBy: null },
+ ]);
+
+ const result = await runCustomModelSync(getDb());
+
+ expect(result.endpoints).toBe(1);
+ expect(result.added).toBe(2);
+ expect(result.skipped).toBe(0);
+ expect(result.failures).toEqual([]);
+ expect(customModelIds()).toEqual(['model-a', 'model-b']);
+ });
+
+ it('skips models already registered on the endpoint and adds the rest', async () => {
+ addCustomEndpoint('http://localhost:9999');
+ getDb().prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, size_label, enabled, endpoint_scope)
+ VALUES ('custom', 'model-a', 'model-a', 50, 50, 'Medium', 1, ?)
+ `).run(endpointScopeForBaseUrl('http://localhost:9999'));
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([
+ { id: 'model-a', ownedBy: null },
+ { id: 'model-b', ownedBy: null },
+ ]);
+
+ const result = await runCustomModelSync(getDb());
+
+ expect(result.added).toBe(1);
+ expect(result.skipped).toBe(1);
+ expect(customModelIds()).toEqual(['model-a', 'model-b']);
+ });
+
+ it('never polls a disabled endpoint', async () => {
+ addDisabledCustomEndpoint('http://off:9999');
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([
+ { id: 'model-a', ownedBy: null },
+ ]);
+
+ const result = await runCustomModelSync(getDb());
+
+ // Turning an endpoint off means "stop using this": the unattended pass must
+ // not reach out to it, nor register (enabled) rows behind the operator's back.
+ expect(discoverEndpointModels).not.toHaveBeenCalled();
+ expect(result.endpoints).toBe(0);
+ expect(result.added).toBe(0);
+ expect(customModelIds()).toEqual([]);
+ });
+
+ it('syncs the enabled endpoint while skipping a disabled one', async () => {
+ addDisabledCustomEndpoint('http://off:9999');
+ addCustomEndpoint('http://on:9999');
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([
+ { id: 'model-a', ownedBy: null },
+ ]);
+
+ const result = await runCustomModelSync(getDb());
+
+ expect(result.endpoints).toBe(1);
+ expect(discoverEndpointModels).toHaveBeenCalledTimes(1);
+ expect((discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mock.calls[0]![0]).toBe('http://on:9999');
+ expect(customModelIds()).toEqual(['model-a']);
+ });
+
+ it('isolates a failing endpoint and keeps syncing the rest', async () => {
+ addCustomEndpoint('http://bad:9999');
+ addCustomEndpoint('http://good:9999');
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>)
+ .mockRejectedValueOnce(new Error('boom'))
+ .mockResolvedValueOnce([{ id: 'model-c', ownedBy: null }]);
+
+ const result = await runCustomModelSync(getDb());
+
+ expect(result.failures).toHaveLength(1);
+ expect(result.failures[0]!.baseUrl).toBe('http://bad:9999');
+ expect(result.failures[0]!.error).toContain('boom');
+ expect(result.added).toBe(1);
+ expect(customModelIds()).toEqual(['model-c']);
+ });
+
+ it('parses the interval env: daily default, 0 disables the scheduled pass', () => {
+ delete process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS;
+ expect(customModelSyncIntervalMs()).toBe(24 * 60 * 60 * 1000);
+
+ process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS = '3600000';
+ expect(customModelSyncIntervalMs()).toBe(3600000);
+
+ process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS = '0';
+ expect(customModelSyncIntervalMs()).toBe(0);
+ expect(startCustomModelSync(getDb(), { every: vi.fn(), after: vi.fn() } as never)).toBeNull();
+ });
+
+ it('parses free patterns from env', () => {
+ const prev = process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ delete process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ expect(customModelSyncFreePatterns()).toEqual([]);
+ process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS = ' *-free, free-* ,paid';
+ expect(customModelSyncFreePatterns()).toEqual(['*-free', 'free-*', 'paid']);
+ if (prev === undefined) delete process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ else process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS = prev;
+ });
+
+ it('skips models that match no free pattern when FREE_PATTERNS is set', async () => {
+ const prev = process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS = '*:free,free-*';
+ addCustomEndpoint('http://localhost:9999');
+ (discoverEndpointModels as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([
+ { id: 'free-model-a', ownedBy: null },
+ { id: 'gpt-oss:free', ownedBy: null },
+ { id: 'paid-model', ownedBy: null },
+ ]);
+
+ const result = await runCustomModelSync(getDb());
+
+ expect(result.added).toBe(2);
+ expect(result.paidSkipped).toBe(1);
+ expect(customModelIds()).toEqual(['free-model-a', 'gpt-oss:free']);
+ if (prev === undefined) delete process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ else process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS = prev;
+ });
+});
diff --git a/server/src/index.ts b/server/src/index.ts
index 093dba17..50800a73 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -6,6 +6,7 @@ import { applyProxyUrl, applyProxyEnabled, applyProxyBypass, flushProxyCache } f
import { startWakeDetect } from './lib/wake-detect.js';
import { startCatalogSync } from './services/catalog-sync.js';
import { startCooldownProbe } from './services/cooldown-probe.js';
+import { startCustomModelSync } from './services/custom-model-sync.js';
import { installProcessSafetyNet } from './lib/process-safety-net.js';
import { NodeScheduler } from './lib/scheduler.js';
import { loadConfig } from './lib/config.js';
@@ -66,6 +67,7 @@ async function main() {
startCatalogSync(scheduler);
startCooldownProbe(scheduler);
startDbBackupPump(getDb(), scheduler, config.dbPath ?? undefined);
+ startCustomModelSync(getDb(), scheduler);
// Post-sleep recovery: while the host was suspended (laptop lid, VM
// pause) timers and keep-alive sockets froze, so the first requests after
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index 9479481d..a4a338a5 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -9,10 +9,11 @@ import { encrypt, decrypt, maskKey } from '../lib/crypto.js';
import { parseKeysFromFile, stripJsoncComments, stripTrailingCommas } from '../lib/key-parser.js';
import { assessProviderUrl } from '../lib/url-guard.js';
import { verifyCredentials } from '../services/auth.js';
-import { ensureModelInProfiles } from '../services/profile-models.js';
import { getActiveCooldownsForKeys, clearCooldownsForKey } from '../services/ratelimit.js';
+import { ensureModelInProfiles } from '../services/profile-models.js';
import { resolveCustomEndpointKey, customEndpointKeyIds, siblingEndpointKeyId, endpointHasCredential } from '../services/custom-endpoint.js';
import { customModelSeed } from '../services/custom-model-seed.js';
+import { registerCustomModels, registerCustomChatModels } from '../services/custom-model-register.js';
import { discoverEndpointModels, probeEndpointModel, ModelDiscoveryError } from '../services/model-discovery.js';
import { probeEmbeddingDimensions, registerCustomEmbeddingModel } from '../services/embeddings.js';
import { endpointScopeForBaseUrl, normalizeBaseUrl } from '../lib/endpoint-scope.js';
@@ -709,109 +710,6 @@ function resolveEndpointRef(ref: { keyId?: number; baseUrl?: string }): CustomEn
return { baseUrl: requestedBaseUrl, keyId: rows[0]?.id ?? null, storedKey: null };
}
-interface CustomChatModelEntry {
- modelId: string;
- displayName: string | null;
- supportsTools?: boolean;
- supportsVision?: boolean;
-}
-
-interface RegisteredCustomModel {
- modelDbId: number;
- model: string;
- displayName: string;
- supportsTools: boolean;
- supportsVision: boolean;
- created: boolean;
-}
-
-/**
- * Register chat models bound to a custom endpoint's key — the shared write
- * path behind POST /custom and the bulk key importer (#382). Runs inside the
- * caller's transaction.
- */
-function registerCustomChatModels(db: Db, baseUrl: string, keyId: number, entries: CustomChatModelEntry[]): RegisteredCustomModel[] {
- const endpointKeyIds = customEndpointKeyIds(db, keyId);
- // The identity discriminator for every row registered in this call (#651).
- const endpointScope = endpointScopeForBaseUrl(baseUrl);
- // Unknown ≠ worst: seed the routing ranks at the catalog median so a new
- // custom model is explored instead of buried at intelligence 0 (#488).
- const seed = customModelSeed(db);
-
- const registered: RegisteredCustomModel[] = [];
- for (const { modelId, displayName, supportsTools, supportsVision } of entries) {
- // Register each model bound to THIS endpoint's key. Custom models carry no
- // rate limits and sort last in the intelligence preset (size_label tier).
- // Identity is per endpoint (#651): the same model id on a DIFFERENT relay
- // is a separate row with its own enabled flag, ranks and stats, instead of
- // silently rebinding the other endpoint's row as it used to. A model
- // already on THIS endpoint keeps the key it has, so adding a second
- // credential doesn't re-bind it (#619).
- // Capability flags: an unset flag binds NULL so COALESCE picks the insert
- // default (tools 1, vision 0) on a new row and preserves the existing
- // value on re-registration. (#470) An omitted display name binds NULL the
- // same way — it falls back to the model id on a new row and leaves a name
- // already on the row alone, so the bulk re-registration behind "Fetch
- // models" (which posts bare ids) can't wipe names the operator set.
- const bound = db.prepare(
- "SELECT key_id FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
- ).get(modelId, endpointScope) as { key_id: number | null } | undefined;
- const created = bound === undefined;
- const bindKeyId = bound?.key_id != null && endpointKeyIds.has(bound.key_id) ? bound.key_id : keyId;
- const toolsParam = supportsTools === undefined ? null : (supportsTools ? 1 : 0);
- const visionParam = supportsVision === undefined ? null : (supportsVision ? 1 : 0);
- // The seed applies on INSERT only: DO UPDATE deliberately leaves the rank
- // columns alone so re-registering a model (or bulk-adding alongside it)
- // never rewrites ranks the operator has since tuned by hand.
- 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, key_id,
- supports_tools, supports_vision, source, endpoint_scope)
- VALUES ('custom', @modelId, COALESCE(@displayName, @modelId), @intelligenceRank, @speedRank, @sizeLabel,
- NULL, NULL, NULL, NULL, '', NULL, 1, @keyId,
- COALESCE(@tools, 1), COALESCE(@vision, 0), 'user', @endpointScope)
- ON CONFLICT(platform, model_id, endpoint_scope)
- DO UPDATE SET
- display_name = COALESCE(@displayName, display_name),
- key_id = excluded.key_id,
- enabled = 1,
- supports_tools = COALESCE(@tools, supports_tools),
- supports_vision = COALESCE(@vision, supports_vision)
- `).run({
- modelId, displayName, keyId: bindKeyId, tools: toolsParam, vision: visionParam,
- intelligenceRank: seed.intelligenceRank, speedRank: seed.speedRank, sizeLabel: seed.sizeLabel,
- endpointScope,
- });
-
- // Read back rather than echo the submitted values: an omitted display name
- // or capability flag resolves in SQL, so the row is the only place that
- // knows what this model is actually called now.
- const modelRow = db.prepare(
- "SELECT id, display_name, supports_tools, supports_vision FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
- ).get(modelId, endpointScope) as { id: number; display_name: string; supports_tools: number; supports_vision: number };
-
- // Append to the fallback chain if not already present.
- const inChain = db.prepare('SELECT 1 FROM fallback_config WHERE model_db_id = ?').get(modelRow.id);
- if (!inChain) {
- 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 (?, ?, 1)').run(modelRow.id, max.m + 1);
- }
- ensureModelInProfiles(db, modelRow.id);
-
- registered.push({
- modelDbId: modelRow.id,
- model: modelId,
- displayName: modelRow.display_name,
- supportsTools: modelRow.supports_tools === 1,
- supportsVision: modelRow.supports_vision === 1,
- created,
- });
- }
-
- return registered;
-}
-
/**
* Models attached to an imported custom endpoint (#382). Ids that look like
* embedding models go through the embeddings path — it needs a dimension, so
@@ -1110,20 +1008,9 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
return;
}
- const upsert = db.transaction(() => {
- // Key rows are matched on (base_url, secret): a new secret for a known
- // endpoint is a SECOND credential for it, not a replacement (#619), and a
- // new base_url is a separate provider (#212). Re-submitting with a blank
- // key preserves the stored one. A submitted keyId pins WHICH credential of
- // the pool the new models bind to (#488 bulk registration).
- const { keyId, storedKey: storedKeyForMask } = resolveCustomEndpointKey(
- db, baseUrl, providedKey, label, endpoint.keyId ?? undefined,
- );
- const registered = registerCustomChatModels(db, baseUrl, keyId, entries);
- return { keyId, registered, storedKeyForMask };
- });
-
- const { keyId, registered, storedKeyForMask } = upsert();
+ const { keyId, storedKey, registered } = registerCustomModels(
+ db, baseUrl, providedKey, label, endpoint.keyId ?? undefined, entries,
+ );
// `model`/`displayName`/`modelDbId` echo the first model for older clients;
// `models` carries the full set registered in this call.
const first = registered[0]!;
@@ -1142,7 +1029,7 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
// picking a whole discovered list re-submits ids that are already there.
created: registered.filter(m => m.created).length,
alreadyRegistered: registered.filter(m => !m.created).length,
- maskedKey: maskKey(storedKeyForMask),
+ maskedKey: maskKey(storedKey),
});
});
diff --git a/server/src/services/custom-endpoint.ts b/server/src/services/custom-endpoint.ts
index 17653aa3..311028b5 100644
--- a/server/src/services/custom-endpoint.ts
+++ b/server/src/services/custom-endpoint.ts
@@ -169,3 +169,45 @@ export function siblingEndpointKeyId(db: Db, keyId: number, baseUrl: string | nu
`).get(baseUrl, keyId) as { id: number } | undefined;
return row?.id ?? null;
}
+
+export interface CustomEndpointCredential {
+ keyId: number;
+ baseUrl: string;
+ /** Decrypted secret, or null when the row's ciphertext cannot be decrypted. */
+ apiKey: string | null;
+}
+
+/**
+ * Every ENABLED custom endpoint, one entry per distinct base_url, carrying its
+ * first stored credential. Used by the scheduled model sync (#674/#663/#656)
+ * to refresh model lists unattended: the manual route asks the operator for a
+ * key mid-typing, but a scheduled pass can only use what the endpoint already
+ * has on record.
+ *
+ * Disabled keys are excluded: turning an endpoint off means "stop using this",
+ * so an unattended pass must not keep polling it and registering new (enabled)
+ * model rows behind the operator's back.
+ */
+export function listCustomEndpoints(db: Db): CustomEndpointCredential[] {
+ const rows = db.prepare(`
+ SELECT base_url, id, encrypted_key, iv, auth_tag
+ FROM api_keys
+ WHERE platform = 'custom' AND base_url IS NOT NULL AND enabled = 1
+ ORDER BY base_url, id
+ `).all() as Array<{
+ base_url: string;
+ id: number;
+ encrypted_key: string;
+ iv: string;
+ auth_tag: string;
+ }>;
+
+ const seen = new Set<string>();
+ const out: CustomEndpointCredential[] = [];
+ for (const row of rows) {
+ if (seen.has(row.base_url)) continue;
+ seen.add(row.base_url);
+ out.push({ keyId: row.id, baseUrl: row.base_url, apiKey: plaintextOf(row) });
+ }
+ return out;
+}
diff --git a/server/src/services/custom-model-register.ts b/server/src/services/custom-model-register.ts
new file mode 100644
index 00000000..9589d4fd
--- /dev/null
+++ b/server/src/services/custom-model-register.ts
@@ -0,0 +1,152 @@
+import type { Db } from '../db/types.js';
+import { resolveCustomEndpointKey, customEndpointKeyIds } from './custom-endpoint.js';
+import { customModelSeed } from './custom-model-seed.js';
+import { ensureModelInProfiles } from './profile-models.js';
+import { endpointScopeForBaseUrl } from '../lib/endpoint-scope.js';
+
+// ── Shared custom-model registration ─────────────────────────────────────────
+//
+// POST /custom, the bulk key importer (#382) and the scheduled custom-model
+// sync (#674/#663/#656) register models against a user's own endpoint through
+// the SAME code path, so they can never drift apart. This used to live inline
+// in routes/keys.ts; it moved here verbatim and the copy there was deleted, so
+// no caller can invent a subtly different notion of "registering a custom
+// model".
+
+/** One model to register against a custom endpoint (POST /custom body entry). */
+export interface CustomModelEntry {
+ modelId: string;
+ displayName: string | null;
+ supportsTools?: boolean;
+ supportsVision?: boolean;
+}
+
+export interface RegisteredCustomModel {
+ modelDbId: number;
+ model: string;
+ displayName: string;
+ supportsTools: boolean;
+ supportsVision: boolean;
+ created: boolean;
+}
+
+export interface RegisterCustomModelsResult {
+ keyId: number;
+ /** The credential this registration bound to, for masking in responses. */
+ storedKey: string;
+ registered: RegisteredCustomModel[];
+}
+
+/**
+ * Register (or re-register) models against a custom endpoint inside one
+ * transaction.
+ *
+ * Key rows are matched on (base_url, secret): a new secret for a known
+ * endpoint is a SECOND credential for it, not a replacement (#619), and a
+ * new base_url is a separate provider (#212). Identity is per endpoint
+ * (#651): the same model id on a DIFFERENT relay is a separate row with its
+ * own enabled flag, ranks and stats, instead of silently rebinding the other
+ * endpoint's row. A model already on THIS endpoint keeps the key it has, so
+ * adding a second credential doesn't re-bind it (#619).
+ *
+ * Capability flags: an unset flag binds NULL so COALESCE picks the insert
+ * default (tools 1, vision 0) on a new row and preserves the existing value
+ * on re-registration (#470). An omitted display name binds NULL the same way
+ * — it falls back to the model id on a new row and leaves a name already on
+ * the row alone, so the bulk re-registration behind "Fetch models" (which
+ * posts bare ids) can't wipe names the operator set.
+ */
+export function registerCustomModels(
+ db: Db,
+ baseUrl: string,
+ providedKey: string | undefined,
+ label: string | undefined,
+ pinnedKeyId: number | undefined,
+ entries: CustomModelEntry[],
+): RegisterCustomModelsResult {
+ return db.transaction(() => {
+ const { keyId, storedKey } = resolveCustomEndpointKey(db, baseUrl, providedKey, label, pinnedKeyId);
+ const registered = registerCustomChatModels(db, baseUrl, keyId, entries);
+ return { keyId, storedKey, registered };
+ })();
+}
+
+/**
+ * The registration loop itself, against an ALREADY-resolved endpoint key and
+ * inside the caller's transaction. Split out from registerCustomModels so the
+ * bulk key importer (#382) — which resolves its own key and owns a wider
+ * transaction — shares this exact write path instead of keeping a second copy.
+ */
+export function registerCustomChatModels(
+ db: Db,
+ baseUrl: string,
+ keyId: number,
+ entries: CustomModelEntry[],
+): RegisteredCustomModel[] {
+ const endpointKeyIds = customEndpointKeyIds(db, keyId);
+ // The identity discriminator for every row registered in this call (#651).
+ const endpointScope = endpointScopeForBaseUrl(baseUrl);
+ // Unknown ≠ worst: seed the routing ranks at the catalog median so a new
+ // custom model is explored instead of buried at intelligence 0 (#488).
+ const seed = customModelSeed(db);
+
+ const registered: RegisteredCustomModel[] = [];
+ for (const { modelId, displayName, supportsTools, supportsVision } of entries) {
+ const bound = db.prepare(
+ "SELECT key_id FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
+ ).get(modelId, endpointScope) as { key_id: number | null } | undefined;
+ const created = bound === undefined;
+ const bindKeyId = bound?.key_id != null && endpointKeyIds.has(bound.key_id) ? bound.key_id : keyId;
+ const toolsParam = supportsTools === undefined ? null : (supportsTools ? 1 : 0);
+ const visionParam = supportsVision === undefined ? null : (supportsVision ? 1 : 0);
+ // The seed applies on INSERT only: DO UPDATE deliberately leaves the rank
+ // columns alone so re-registering a model (or bulk-adding alongside it)
+ // never rewrites ranks the operator has since tuned by hand.
+ 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, key_id,
+ supports_tools, supports_vision, source, endpoint_scope)
+ VALUES ('custom', @modelId, COALESCE(@displayName, @modelId), @intelligenceRank, @speedRank, @sizeLabel,
+ NULL, NULL, NULL, NULL, '', NULL, 1, @keyId,
+ COALESCE(@tools, 1), COALESCE(@vision, 0), 'user', @endpointScope)
+ ON CONFLICT(platform, model_id, endpoint_scope)
+ DO UPDATE SET
+ display_name = COALESCE(@displayName, display_name),
+ key_id = excluded.key_id,
+ enabled = 1,
+ supports_tools = COALESCE(@tools, supports_tools),
+ supports_vision = COALESCE(@vision, supports_vision)
+ `).run({
+ modelId, displayName, keyId: bindKeyId, tools: toolsParam, vision: visionParam,
+ intelligenceRank: seed.intelligenceRank, speedRank: seed.speedRank, sizeLabel: seed.sizeLabel,
+ endpointScope,
+ });
+
+ // Read back rather than echo the submitted values: an omitted display name
+ // or capability flag resolves in SQL, so the row is the only place that
+ // knows what this model is actually called now.
+ const modelRow = db.prepare(
+ "SELECT id, display_name, supports_tools, supports_vision FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
+ ).get(modelId, endpointScope) as { id: number; display_name: string; supports_tools: number; supports_vision: number };
+
+ // Append to the fallback chain if not already present.
+ const inChain = db.prepare('SELECT 1 FROM fallback_config WHERE model_db_id = ?').get(modelRow.id);
+ if (!inChain) {
+ 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 (?, ?, 1)').run(modelRow.id, max.m + 1);
+ }
+ ensureModelInProfiles(db, modelRow.id);
+
+ registered.push({
+ modelDbId: modelRow.id,
+ model: modelId,
+ displayName: modelRow.display_name,
+ supportsTools: modelRow.supports_tools === 1,
+ supportsVision: modelRow.supports_vision === 1,
+ created,
+ });
+ }
+
+ return registered;
+}
diff --git a/server/src/services/custom-model-sync.ts b/server/src/services/custom-model-sync.ts
new file mode 100644
index 00000000..c5528e6c
--- /dev/null
+++ b/server/src/services/custom-model-sync.ts
@@ -0,0 +1,123 @@
+import type { Db } from '../db/types.js';
+import type { Scheduler } from '../lib/scheduler.js';
+import { discoverEndpointModels } from './model-discovery.js';
+import { registerCustomModels, type CustomModelEntry } from './custom-model-register.js';
+import { listCustomEndpoints } from './custom-endpoint.js';
+import { endpointScopeForBaseUrl } from '../lib/endpoint-scope.js';
+
+// ── Scheduled custom-model sync (#674/#663/#656) ─────────────────────────────
+//
+// Operators add a custom OpenAI-compatible provider and fetch its model list
+// once, but providers change their model availability almost daily. This walks
+// every configured custom endpoint on a schedule and registers whatever NEW
+// models it now serves, reusing the exact same registration path as the manual
+// POST /custom (see custom-model-register.ts) so the two can never drift.
+//
+// Deliberate bounds:
+// - ADD ONLY. Models that disappear upstream are left alone — an automated
+// pass must never delete a row the operator may have tuned by hand.
+// - One failing endpoint is logged and skipped; the others still sync, so a
+// dead relay cannot hold the whole schedule hostage.
+// - No catalog paywall interplay: these models come from the operator's own
+// endpoint with the operator's own key, not from the published catalog.
+
+/** Default: once a day (#674 asks for daily; #663's 5-minute ask targets the
+ * bundled free catalog, which this pass deliberately never touches). */
+const DEFAULT_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** Interval in ms from `CUSTOM_MODEL_SYNC_INTERVAL_MS`; 0 disables the pass,
+ * anything unset or malformed falls back to the daily default. */
+export function customModelSyncIntervalMs(): number {
+ const raw = process.env.CUSTOM_MODEL_SYNC_INTERVAL_MS;
+ if (raw === undefined || raw.trim() === '') return DEFAULT_SYNC_INTERVAL_MS;
+ const ms = Number(raw);
+ return Number.isFinite(ms) && ms >= 0 ? ms : DEFAULT_SYNC_INTERVAL_MS;
+}
+
+/** Comma-separated glob patterns of model ids that are known-free (#746).
+ * When set, the sync registers ONLY models matching a pattern — anything else
+ * (presumably paid) is skipped, honoring the repo's free-only policy. When
+ * unset, the sync keeps its legacy behavior of registering everything, so
+ * existing operators are unaffected. */
+export function customModelSyncFreePatterns(): string[] {
+ const raw = process.env.CUSTOM_MODEL_SYNC_FREE_PATTERNS;
+ if (raw === undefined || raw.trim() === '') return [];
+ return raw.split(',').map(p => p.trim()).filter(p => p.length > 0);
+}
+
+/** Glob match where `*` matches any run of chars (incl. empty). */
+function patternMatches(pattern: string, id: string): boolean {
+ const escaped = pattern.split('*').map(seg => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+ return new RegExp(`^${escaped.join('.*')}$`).test(id);
+}
+
+export interface CustomModelSyncResult {
+ endpoints: number;
+ /** Models registered for the first time. */
+ added: number;
+ /** Models already on this endpoint that were skipped. */
+ skipped: number;
+ /** Models skipped because they matched no free pattern (#746). */
+ paidSkipped: number;
+ failures: Array<{ baseUrl: string; error: string }>;
+}
+
+/** Sync every configured custom endpoint once. Exported so tests (and an admin
+ * that wants a manual pass) can run it directly without waiting for the timer. */
+export async function runCustomModelSync(db: Db): Promise<CustomModelSyncResult> {
+ const endpoints = listCustomEndpoints(db);
+ const result: CustomModelSyncResult = { endpoints: endpoints.length, added: 0, skipped: 0, paidSkipped: 0, failures: [] };
+
+ for (const endpoint of endpoints) {
+ try {
+ // A submitted key wins on the manual route; a scheduled pass can only use
+ // what the endpoint already has on record. Keyless local servers keep the
+ // 'no-key' sentinel, which the bearer header carries harmlessly.
+ const discovered = await discoverEndpointModels(endpoint.baseUrl, endpoint.apiKey ?? 'no-key');
+
+ const scope = endpointScopeForBaseUrl(endpoint.baseUrl);
+ const registeredIds = new Set(
+ (db.prepare("SELECT model_id FROM models WHERE platform = 'custom' AND endpoint_scope = ?").all(scope) as { model_id: string }[])
+ .map(row => row.model_id),
+ );
+
+ const freePatterns = customModelSyncFreePatterns();
+ const fresh: CustomModelEntry[] = [];
+ for (const model of discovered) {
+ if (registeredIds.has(model.id)) {
+ result.skipped += 1;
+ continue;
+ }
+ // Free-only policy (#746): when FREE_PATTERNS is configured, a model
+ // that matches none of the known-free patterns is presumably paid and
+ // is skipped rather than silently registered.
+ if (freePatterns.length > 0 && !freePatterns.some(p => patternMatches(p, model.id))) {
+ result.paidSkipped += 1;
+ continue;
+ }
+ // Bare id only, like the dashboard's bulk "Fetch models" submit: no name
+ // or capability claims invented here, they resolve in SQL on insert.
+ fresh.push({ modelId: model.id, displayName: null });
+ }
+
+ if (fresh.length > 0) {
+ const registered = registerCustomModels(db, endpoint.baseUrl, undefined, undefined, endpoint.keyId, fresh);
+ result.added += registered.registered.filter(m => m.created).length;
+ }
+ } catch (err: any) {
+ const message = err?.message ?? String(err);
+ result.failures.push({ baseUrl: endpoint.baseUrl, error: message });
+ console.error(`[custom-model-sync] ${endpoint.baseUrl}: ${message}`);
+ }
+ }
+
+ return result;
+}
+
+/** Register the daily pass on the server's scheduler. Returns null when the
+ * interval is configured to 0 (disabled). */
+export function startCustomModelSync(db: Db, scheduler: Scheduler): (() => void) | null {
+ const intervalMs = customModelSyncIntervalMs();
+ if (intervalMs <= 0) return null;
+ return scheduler.every(intervalMs, () => { void runCustomModelSync(db); }, { name: 'custom-model-sync' });
+}