Skip to content
Python

Custom providers: permanent add box, named cards, fetch models from server

Rohit C Prasadfc6ca8a70314
diff --git a/README.md b/README.md
index fb145804..63733613 100644
--- a/README.md
+++ b/README.md
@@ -91,7 +91,7 @@ Model access is yours: pick a provider, paste your key, switch anytime. Supporte
A curated model list marks what we've verified for tool-calling work. Adding any model string works at your own risk.
-Need another Chat Completions gateway? In **Settings → Models**, choose **Custom provider** and enter its endpoint, Bearer API key, and a short route prefix. Add the gateway's model IDs manually; for example, an OpenRouter route named `openrouter` uses `openrouter:anthropic/claude-…`. This supports standard OpenAI-compatible APIs without OpenWorker maintaining their full catalog.
+Another OpenAI-compatible server — a gateway, a proxy, a vendor not listed? In **Settings ▸ Models & Keys**, the **Add an OpenAI-compatible provider** box at the end of the API-keys group takes a name, its endpoint and key; it becomes its own card, and its models are selected as `<prefix>:<model-id>` (the prefix is derived from the name). Type the model ids, or fetch them from the server when it lists them.
## Privacy
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 8f578b1b..303270d7 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -4424,7 +4424,7 @@ class SessionManager:
fresh-sandbox gpt-5.6-sol case; owner-hit on a sandbox 2026-09-02).
A default that already works is never stolen. Returns the model
adopted, if any."""
- d = get_descriptor(name)
+ d = get_descriptor(name, self.secrets)
if d is None:
return None
self._refresh_provider(name)
@@ -4704,8 +4704,61 @@ class SessionManager:
profile = self.secrets.get(f"provider:{name}") or {}
rows = local_server.model_facts(name, profile.get("base_url"), profile.get("api_key"), fresh=True)
return {"provider": name, "models": rows, "alive": self._local_server_alive(name)}
+ if is_custom_provider(name, self.secrets):
+ return self._custom_provider_models(name)
return {"provider": name, "models": [], "error": "no local model list for this provider"}
+ def _custom_provider_models(self, name: str) -> dict[str, Any]:
+ """The ids a user-added OpenAI-compatible provider lists at GET /models, as rows the
+ settings page can tick ("Fetch from server"). A server without /models is not a
+ broken provider — Chat Completions does not require the listing — so that case
+ comes back as a note, and the user types the ids instead."""
+ import httpx
+
+ profile = self.secrets.get(f"provider:{name}") or {}
+ base = str(profile.get("base_url") or "").strip().rstrip("/")
+ key = str(profile.get("api_key") or "").strip()
+ if not base:
+ return {"provider": name, "models": [], "error": "No endpoint saved for this provider."}
+ try:
+ resp = httpx.get(
+ base + "/models",
+ headers={"Authorization": f"Bearer {key}"} if key else {},
+ timeout=8.0,
+ )
+ except Exception as exc: # noqa: BLE001 - a listing never raises into the route
+ return {
+ "provider": name,
+ "models": [],
+ "alive": False,
+ "error": f"Could not reach {base}: {exc.__class__.__name__}.",
+ }
+ if resp.status_code in (404, 405):
+ return {
+ "provider": name,
+ "models": [],
+ "alive": True,
+ "error": "This server does not list its models (no /models). Type the model ids by hand.",
+ }
+ if resp.status_code >= 300:
+ return {"provider": name, "models": [], "alive": True, "error": f"HTTP {resp.status_code} from {base}/models."}
+ try:
+ data = resp.json()
+ except ValueError:
+ return {"provider": name, "models": [], "alive": True, "error": f"{base}/models did not answer with JSON."}
+ items = data.get("data") if isinstance(data, dict) else data
+ ids = [str(it["id"]) for it in items if isinstance(it, dict) and it.get("id")] if isinstance(items, list) else []
+ rows = [
+ {
+ "model": f"{name}:{mid}", "name": mid, "size_bytes": None, "tools": None,
+ "thinking": None, "vision": None, "remote": True, "parameter_size": None,
+ "quantization": None, "context_max": None, "context": None,
+ "context_from": "server", "fit": "cloud", "recommendation": None,
+ }
+ for mid in ids
+ ]
+ return {"provider": name, "models": rows, "alive": True}
+
def _local_server_alive(self, name: str) -> bool:
"""Best-effort liveness of an OpenAI-compatible local server (local_server.LOCAL_SERVERS), cached 30 s like Ollama's."""
import time
diff --git a/surfaces/gui/e2e/custom-provider.spec.ts b/surfaces/gui/e2e/custom-provider.spec.ts
new file mode 100644
index 00000000..e17de03f
--- /dev/null
+++ b/surfaces/gui/e2e/custom-provider.spec.ts
@@ -0,0 +1,68 @@
+// Settings ▸ Models & Keys: the permanent "Add an OpenAI-compatible provider" box at the end
+// of the API-keys group (PR #224 design, owner follow-up 2026-10-26). Saving it creates a card
+// named by the user; the card's models are typed or fetched from the server; removing the
+// provider removes the card. The add box stays through all of it.
+import { expect } from "@playwright/test";
+import { test } from "./fixtures";
+
+async function openModels(page) {
+ await page.goto("/");
+ await page.getByTestId("account-row").click();
+ await page.getByRole("button", { name: "Settings", exact: true }).click();
+ await page.getByRole("button", { name: "Models & Keys" }).click();
+ await expect(page.getByTestId("set-provider-openai")).toBeVisible();
+}
+
+test("the add box makes a named card, which lists its server's models and can be removed", async ({ page }) => {
+ await openModels(page);
+ // The box sits in the API-keys group, visible without expanding the fold.
+ const addBox = page.getByTestId("provider-grid-api_key").getByTestId("set-provider-custom-add");
+ await expect(addBox).toContainText("Add an OpenAI-compatible provider");
+ await addBox.click();
+
+ await page.getByTestId("custom-provider-title").fill("Acme Gateway");
+ await expect(page.getByTestId("custom-provider-route")).toHaveValue("acme-gateway");
+ await page.getByTestId("custom-provider-endpoint").fill("https://llm.acme.example/v1");
+ await page.getByTestId("custom-provider-key").fill("acme-test");
+ await page.getByTestId("custom-provider-add").click();
+
+ // The new card opened: the user's name on it, the endpoint shown, "Remove provider…" offered.
+ await expect(page.locator("main")).toContainText("Acme Gateway");
+ await expect(page.getByTestId("set-field-base_url")).toHaveValue("https://llm.acme.example/v1");
+ await expect(page.getByTestId("set-remove-key")).toContainText("Remove provider");
+
+ // Fetch from server lists the ids; ticking one adds it under the route prefix.
+ await page.getByTestId("custom-fetch-models").click();
+ await expect(page.getByTestId("custom-fetch-note")).toContainText("2 models listed");
+ const added = page.waitForRequest((r) => r.url().endsWith("/v1/settings/models/add") && r.method() === "POST");
+ await page.locator(".mlist-row", { hasText: "acme-large" }).getByRole("checkbox").click();
+ expect((await added).postDataJSON()).toEqual({ model: "acme-gateway:acme-large" });
+
+ // Back in the gallery: the card wears the name, and the add box is still there.
+ await page.getByTestId("set-back").click();
+ const card = page.getByTestId("set-provider-acme-gateway");
+ await expect(card).toContainText("Acme Gateway");
+ await expect(card).toContainText("✓ Connected");
+ await expect(page.getByTestId("set-provider-custom-add")).toBeVisible();
+
+ // Remove provider… takes the card away.
+ page.once("dialog", (d) => d.accept());
+ await card.click();
+ await page.getByTestId("set-remove-key").click();
+ await expect(page.getByTestId("set-provider-acme-gateway")).toHaveCount(0);
+ await expect(page.getByTestId("set-provider-custom-add")).toBeVisible();
+});
+
+test("a built-in provider's name is refused as a route prefix", async ({ page }) => {
+ await openModels(page);
+ await page.getByTestId("set-provider-custom-add").click();
+ await page.getByTestId("custom-provider-title").fill("OpenAI");
+ await page.getByTestId("custom-provider-endpoint").fill("https://proxy.example/v1");
+ await page.getByTestId("custom-provider-key").fill("k");
+ await page.getByTestId("custom-provider-add").click();
+ await expect(page.getByTestId("custom-provider-error")).toContainText("already in use");
+ // The form stays; the user picks another prefix.
+ await page.getByTestId("custom-provider-route").fill("my-openai-proxy");
+ await page.getByTestId("custom-provider-add").click();
+ await expect(page.getByTestId("set-field-base_url")).toHaveValue("https://proxy.example/v1");
+});
diff --git a/surfaces/gui/e2e/docs-screenshots.spec.ts b/surfaces/gui/e2e/docs-screenshots.spec.ts
new file mode 100644
index 00000000..887d8df1
--- /dev/null
+++ b/surfaces/gui/e2e/docs-screenshots.spec.ts
@@ -0,0 +1,70 @@
+// Screenshots for docs/assets and PR bodies, light and dark, from the hermetic mock.
+// Opt-in: `DOCS_SHOTS=1 npx playwright test e2e/docs-screenshots.spec.ts` writes the PNGs;
+// a normal run skips this file.
+import path from "node:path";
+import { expect } from "@playwright/test";
+import { test } from "./fixtures";
+
+const OUT = process.env.DOCS_SHOTS_DIR || path.resolve(process.cwd(), "../../docs/assets");
+test.skip(!process.env.DOCS_SHOTS, "set DOCS_SHOTS=1 to refresh the docs screenshots");
+
+const localServer = (name: string, title: string, placeholder: string) => ({
+ name, title, kind: "local", needs_key: false, configured: false, values: {}, suggested_models: [], recommended_model: null,
+ fields: [
+ { key: "base_url", label: "Server address", secret: false, required: false, help: "", placeholder },
+ { key: "api_key", label: "API key (only if the server was started with one)", secret: true, required: false, help: "", placeholder: "" },
+ ],
+});
+
+async function openModels(page) {
+ await page.goto("/");
+ await page.getByTestId("account-row").click();
+ await page.getByRole("button", { name: "Settings", exact: true }).click();
+ await page.getByRole("button", { name: "Models & Keys" }).click();
+ await expect(page.getByTestId("provider-groups")).toBeVisible();
+}
+
+for (const scheme of ["light", "dark"] as const) {
+ const suffix = scheme === "dark" ? "-dark" : "";
+
+ test(`custom provider: add box, saved card, form (${scheme})`, async ({ page }) => {
+ await page.emulateMedia({ colorScheme: scheme });
+ await page.setViewportSize({ width: 1280, height: 900 });
+ await openModels(page);
+ await page.getByTestId("set-provider-custom-add").click();
+ await page.getByTestId("custom-provider-title").fill("Acme Gateway");
+ await page.getByTestId("custom-provider-endpoint").fill("https://llm.acme.example/v1");
+ await page.getByTestId("custom-provider-key").fill("acme-test");
+ await page.screenshot({ path: path.join(OUT, `models-custom-provider-form${suffix}.png`) });
+ await page.getByTestId("custom-provider-add").click();
+ await expect(page.getByTestId("set-field-base_url")).toHaveValue("https://llm.acme.example/v1");
+ await page.getByTestId("set-back").click();
+ await expect(page.getByTestId("set-provider-acme-gateway")).toBeVisible();
+ await page.screenshot({ path: path.join(OUT, `models-custom-provider${suffix}.png`) });
+ });
+
+ test(`local servers group (${scheme})`, async ({ page }) => {
+ await page.route("**/v1/providers", (route) =>
+ route.fulfill({
+ json: [
+ { name: "ollama", title: "Ollama", kind: "local", needs_key: false, configured: true, values: {}, suggested_models: [], recommended_model: null, alive: true, fields: [] },
+ localServer("llamacpp", "llama.cpp", "http://localhost:8080"),
+ localServer("vllm", "vLLM", "http://localhost:8000"),
+ localServer("lmstudio", "LM Studio", "http://localhost:1234"),
+ localServer("jan", "Jan", "http://127.0.0.1:1337"),
+ localServer("docker", "Docker Model Runner", "http://localhost:12434/engines"),
+ localServer("mlx", "mlx-lm", "http://127.0.0.1:8080"),
+ ],
+ }),
+ );
+ await page.emulateMedia({ colorScheme: scheme });
+ await page.setViewportSize({ width: 1280, height: 900 });
+ await openModels(page);
+ await expect(page.getByTestId("set-provider-mlx")).toBeVisible();
+ // Seven local servers: open the fold so every row is in the picture.
+ const more = page.getByTestId("provider-more-local");
+ if (await more.isVisible()) await more.click();
+ await expect(page.getByTestId("set-provider-vllm")).toBeVisible();
+ await page.screenshot({ path: path.join(OUT, `models-local-servers${suffix}.png`) });
+ });
+}
diff --git a/surfaces/gui/e2e/fixtures.ts b/surfaces/gui/e2e/fixtures.ts
index 434f1a08..e12cb978 100644
--- a/surfaces/gui/e2e/fixtures.ts
+++ b/surfaces/gui/e2e/fixtures.ts
@@ -2025,6 +2025,36 @@ export async function mockApi(page: import("@playwright/test").Page) {
? json({ ok: false, error: "Invalid API key." })
: json({ ok: true });
}
+ // a user-added OpenAI-compatible provider (backend create_custom_provider parity): the
+ // slug is checked, a built-in's name is refused, the card appears configured.
+ if (p.endsWith("/v1/providers/custom") && m === "POST") {
+ const b = req.postDataJSON();
+ const name = String(b.name || "").toLowerCase();
+ if (!/^[a-z][a-z0-9_-]{0,31}$/.test(name))
+ return json({ ok: false, error: "Route prefix must start with a letter and use only lowercase letters, numbers, - or _." });
+ if (providers.some((x) => x.name === name)) return json({ ok: false, error: "That route prefix is already in use." });
+ providers.push({
+ name, title: String(b.title || name), needs_key: true, is_custom: true, kind: "api_key",
+ blurb: "Uses the standard OpenAI Chat Completions API. Add model IDs manually below.",
+ fields: [
+ { key: "api_key", label: `${b.title} API key`, secret: true, required: true, help: "", placeholder: "" },
+ { key: "base_url", label: "Endpoint", secret: false, required: true, help: "An HTTPS OpenAI-compatible API base URL ending in /v1. HTTP is allowed only for local gateways.", placeholder: "https://…/v1" },
+ ],
+ configured: true, values: { base_url: b.fields?.base_url }, suggested_models: [], recommended_model: null,
+ key_set_at: "2026-10-26", last_used_at: null,
+ });
+ return json({ ok: true, provider: name, recommended_model: null });
+ }
+ // a custom provider's "Fetch from server": what its GET /models lists.
+ if (/\/v1\/providers\/[^/]+\/models$/.test(p) && m === "GET") {
+ const name = p.split("/").slice(-2)[0];
+ const prov = providers.find((x) => x.name === name);
+ if (prov?.is_custom) {
+ const row = (id: string) => ({ model: `${name}:${id}`, name: id, size_bytes: null, tools: null, thinking: null, vision: null, remote: true, parameter_size: null, quantization: null, context_max: null, context: null, context_from: "server", fit: "cloud", recommendation: null });
+ return json({ provider: name, alive: true, models: [row("acme-large"), row("acme-small")] });
+ }
+ return json({ provider: name, models: [], error: "no local model list for this provider" });
+ }
// save a provider key — flips `configured`, stamps key_set_at (backend set_provider parity).
if (p.endsWith("/v1/providers") && m === "POST") {
const b = req.postDataJSON();
@@ -2047,6 +2077,11 @@ export async function mockApi(page: import("@playwright/test").Page) {
const name = p.split("/").pop()!;
const prov = providers.find((x) => x.name === name);
if (!prov) return json({ ok: false, error: `unknown provider: ${name}` });
+ if (prov.is_custom) {
+ // Removing a custom provider removes the card itself (backend remove_provider parity).
+ providers.splice(providers.indexOf(prov), 1);
+ return json({ ok: true, provider: name });
+ }
prov.configured = !prov.needs_key; // keyless (ollama) stays "configured"
prov.key_set_at = null;
return json({ ok: true, provider: name });
diff --git a/surfaces/gui/src/components/ManageTabs.test.tsx b/surfaces/gui/src/components/ManageTabs.test.tsx
index 39f4072d..18a2251b 100644
--- a/surfaces/gui/src/components/ManageTabs.test.tsx
+++ b/surfaces/gui/src/components/ManageTabs.test.tsx
@@ -1,92 +1,100 @@
+// The "Add an OpenAI-compatible provider" box (PR #224 design, owner follow-up): the route
+// prefix follows the name until edited, saving creates a card named by the user and opens
+// it, and "Fetch from server" offers the ids the server lists.
import { afterEach, expect, it, vi } from "vitest";
import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
-import { ModelsTab } from "./ManageTabs";
+import { ModelsTab, routePrefixFor } from "./ManageTabs";
afterEach(() => {
cleanup();
vi.unstubAllGlobals();
});
-it("creates a custom provider and opens its manual-model configuration", async () => {
+it("derives the route prefix from the name", () => {
+ expect(routePrefixFor("Acme Gateway")).toBe("acme-gateway");
+ expect(routePrefixFor(" My LLM proxy #2 ")).toBe("my-llm-proxy-2");
+ expect(routePrefixFor("42 Labs")).toBe("labs");
+ expect(routePrefixFor("x".repeat(40))).toHaveLength(32);
+});
+
+function stubApi() {
let created = false;
const calls: Array<{ url: string; method: string; body?: unknown }> = [];
vi.stubGlobal(
"fetch",
vi.fn(async (url: string, init?: RequestInit) => {
const method = (init?.method || "GET").toUpperCase();
- calls.push({
- url,
- method,
- body: init?.body ? JSON.parse(String(init.body)) : undefined,
- });
+ calls.push({ url, method, body: init?.body ? JSON.parse(String(init.body)) : undefined });
if (url.includes("/v1/providers/custom") && method === "POST") {
created = true;
- return { json: async () => ({ ok: true, provider: "openrouter" }) } as Response;
+ return { json: async () => ({ ok: true, provider: "acme-gateway" }) } as Response;
+ }
+ if (url.includes("/v1/providers/acme-gateway/models")) {
+ return {
+ ok: true,
+ json: async () => ({
+ provider: "acme-gateway",
+ alive: true,
+ models: [
+ { model: "acme-gateway:acme-large", name: "acme-large" },
+ { model: "acme-gateway:acme-small", name: "acme-small" },
+ ],
+ }),
+ } as Response;
}
if (url.includes("/v1/providers")) {
const providers: any[] = [
{
- name: "openai",
- title: "OpenAI",
- needs_key: true,
- fields: [{ key: "api_key", label: "OpenAI API key", secret: true, required: true }],
- configured: false,
- values: {},
- suggested_models: [],
+ name: "openai", title: "OpenAI", needs_key: true, configured: false, values: {}, suggested_models: [],
recommended_model: "gpt-5.6-sol",
+ fields: [{ key: "api_key", label: "OpenAI API key", secret: true, required: true }],
},
];
if (created) {
providers.push({
- name: "openrouter",
- title: "OpenRouter",
- needs_key: true,
+ name: "acme-gateway", title: "Acme Gateway", needs_key: true, is_custom: true, configured: true,
+ values: { base_url: "https://llm.acme.example/v1" }, suggested_models: [], recommended_model: null,
fields: [
- { key: "api_key", label: "OpenRouter API key", secret: true, required: true },
+ { key: "api_key", label: "Acme Gateway API key", secret: true, required: true },
{ key: "base_url", label: "Endpoint", secret: false, required: true, placeholder: "https://…/v1" },
],
- configured: true,
- values: { base_url: "https://openrouter.ai/api/v1" },
- suggested_models: [],
- recommended_model: null,
- is_custom: true,
});
}
return { json: async () => providers } as Response;
}
if (url.includes("/v1/settings")) {
- return {
- json: async () => ({
- model: "gpt-5.6-sol",
- models: ["gpt-5.6-sol"],
- model_labels: {},
- source: null,
- }),
- } as Response;
+ return { json: async () => ({ ok: true, model: "gpt-5.6-sol", models: ["gpt-5.6-sol"], model_labels: {}, source: null }) } as Response;
}
return { json: async () => ({ ok: true }) } as Response;
}),
);
+ return calls;
+}
+it("creates a named provider from the add box and opens its card", async () => {
+ const calls = stubApi();
render(<ModelsTab />);
fireEvent.click(await screen.findByTestId("set-provider-custom-add"));
- fireEvent.change(screen.getByLabelText("Provider name"), { target: { value: "OpenRouter" } });
- fireEvent.change(screen.getByLabelText("Route prefix"), { target: { value: "openrouter" } });
- fireEvent.change(screen.getByLabelText("Endpoint"), { target: { value: "https://openrouter.ai/api/v1" } });
- fireEvent.change(screen.getByLabelText("API key"), { target: { value: "or-test" } });
- fireEvent.click(screen.getByRole("button", { name: "Add provider" }));
+ fireEvent.change(screen.getByTestId("custom-provider-title"), { target: { value: "Acme Gateway" } });
+ // The prefix follows the name until the user edits it.
+ expect((screen.getByTestId("custom-provider-route") as HTMLInputElement).value).toBe("acme-gateway");
+ fireEvent.change(screen.getByTestId("custom-provider-endpoint"), { target: { value: "https://llm.acme.example/v1" } });
+ fireEvent.change(screen.getByTestId("custom-provider-key"), { target: { value: "acme-test" } });
+ fireEvent.click(screen.getByTestId("custom-provider-add"));
await waitFor(() => {
- expect(calls.find((c) => c.url.includes("/v1/providers/custom")))?.toMatchObject({
+ expect(calls.find((c) => c.url.includes("/v1/providers/custom"))).toMatchObject({
method: "POST",
- body: {
- name: "openrouter",
- title: "OpenRouter",
- fields: { base_url: "https://openrouter.ai/api/v1", api_key: "or-test" },
- },
+ body: { name: "acme-gateway", title: "Acme Gateway", fields: { base_url: "https://llm.acme.example/v1", api_key: "acme-test" } },
});
});
- expect((await screen.findByTestId("set-field-base_url") as HTMLInputElement).value).toBe(
- "https://openrouter.ai/api/v1",
- );
+ // The new card opens: its endpoint is shown (required, so never behind the disclosure).
+ expect(((await screen.findByTestId("set-field-base_url")) as HTMLInputElement).value).toBe("https://llm.acme.example/v1");
+ expect(screen.getByTestId("set-remove-key").textContent).toContain("Remove provider");
+
+ // Fetch from server lists the ids as rows to tick.
+ fireEvent.click(screen.getByTestId("custom-fetch-models"));
+ await waitFor(() => expect(screen.getByTestId("custom-fetch-note").textContent).toContain("2 models listed"));
+ expect(screen.getByTitle("acme-gateway:acme-large")).toBeTruthy();
+ expect(screen.getByTitle("acme-gateway:acme-small")).toBeTruthy();
});
diff --git a/surfaces/gui/src/components/ManageTabs.tsx b/surfaces/gui/src/components/ManageTabs.tsx
index 96f46a9c..898c04a5 100644
--- a/surfaces/gui/src/components/ManageTabs.tsx
+++ b/surfaces/gui/src/components/ManageTabs.tsx
@@ -7,6 +7,7 @@ import {
connectManaged,
connectMcpBacked,
createCustomProvider,
+ getLocalModels,
disallowUser,
getSettings,
getSubscriptions,
@@ -102,6 +103,11 @@ export function ModelsTab() {
const [settingsError, setSettingsError] = useState(false);
const [addingCustom, setAddingCustom] = useState(false);
const [openCustom, setOpenCustom] = useState<string | null>(null);
+ // A custom provider's "Fetch from server": the ids its GET /models listed (offered as
+ // suggestions in the checklist) and the one-line outcome.
+ const [fetched, setFetched] = useState<string[]>([]);
+ const [fetching, setFetching] = useState(false);
+ const [fetchNote, setFetchNote] = useState<string | null>(null);
const refreshSettings = () => {
setSettingsError(false);
getSettings()
@@ -130,6 +136,26 @@ export function ModelsTab() {
}
}, [openCustom, ps.providers]);
+ useEffect(() => {
+ setFetched([]);
+ setFetchNote(null);
+ }, [ps.sel]);
+
+ const fetchModels = async () => {
+ if (!ps.sel) return;
+ setFetching(true);
+ setFetchNote(null);
+ try {
+ const res = await getLocalModels(ps.sel);
+ const ids = res.models.map((m) => m.name);
+ setFetched(ids);
+ setFetchNote(res.error || (ids.length ? t("manage.custom_fetched_count", { count: ids.length }) : t("manage.custom_fetched_none")));
+ } catch {
+ setFetchNote(t("manage.local_models_failed"));
+ }
+ setFetching(false);
+ };
+
// #43: a failed or hung settings fetch says so and offers Retry (same shape as the
// local-models status line below) instead of sitting on "Loading…" forever.
if (settingsError) {
@@ -219,12 +245,20 @@ export function ModelsTab() {
<div className="mt-6">
<div className={SEC_H + " mb-1.5"}>{t("manage.models")}</div>
<p className="text-meta text-muted mb-2.5 leading-relaxed">
- {t("manage.models_help")}
+ {t(info?.is_custom ? "manage.custom_models_help" : "manage.models_help")}
</p>
+ {info?.is_custom && (
+ <div className="flex items-center gap-3 mb-2.5" data-testid="custom-fetch-row">
+ <button className={BTN_BORDERED} data-testid="custom-fetch-models" disabled={fetching} onClick={() => void fetchModels()}>
+ {fetching ? t("manage.custom_fetching") : t("manage.custom_fetch_models")}
+ </button>
+ {fetchNote && <span className="text-meta text-muted" data-testid="custom-fetch-note">{fetchNote}</span>}
+ </div>
+ )}
<ModelChecklist
provider={ps.sel}
knownProviders={knownNames}
- suggested={info?.suggested_models || []}
+ suggested={[...(info?.suggested_models || []), ...fetched].filter((m, i, a) => a.indexOf(m) === i)}
curated={settings.models}
defaultModel={settings.model}
labels={settings.model_labels}
@@ -261,8 +295,22 @@ export function ModelsTab() {
);
}
-/** First-run form for a generic OpenAI-compatible provider. It intentionally does
- * not fetch a model catalog: users add the exact model ids their gateway exposes. */
+/** A route prefix from a display name: lowercase, dashes between words, starting with a
+ * letter, at most 32 characters — the slug the backend accepts for `<prefix>:<model-id>`. */
+export function routePrefixFor(title: string): string {
+ return title
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-+|-+$/g, "")
+ .replace(/^[^a-z]+/, "")
+ .slice(0, 32)
+ .replace(/-+$/, "");
+}
+
+/** The form behind the "Add an OpenAI-compatible provider" box: a name of the user's
+ * choosing (the new card's title), the route prefix derived from it (editable until the
+ * first save), the endpoint and the key. Saving creates the card and opens it, where the
+ * model ids are typed or fetched from the server. */
function CustomProviderForm({
onCancel,
onCreated,
@@ -270,49 +318,97 @@ function CustomProviderForm({
onCancel: () => void;
onCreated: (name: string) => Promise<void>;
}) {
+ const { t } = useTranslation();
const [title, setTitle] = useState("");
const [name, setName] = useState("");
+ const [nameTouched, setNameTouched] = useState(false);
const [baseUrl, setBaseUrl] = useState("");
const [apiKey, setApiKey] = useState("");
const [error, setError] = useState<string | null>(null);
const [saving, setSaving] = useState(false);
- const input = "w-full px-3 py-2 rounded-lg border border-line bg-panel text-[13.5px] outline-none focus:border-accent";
+ const input = "w-full px-3 py-2 rounded-lg border border-line bg-panel text-ui outline-none focus:border-accent";
+ const label = "block text-meta text-muted mt-3 mb-1";
+ const prefix = name || routePrefixFor(title);
const save = async () => {
setSaving(true);
setError(null);
const result: { ok: boolean; error?: string; provider?: string } = await createCustomProvider(
- name,
+ prefix,
title,
{ base_url: baseUrl, api_key: apiKey },
- ).catch(() => ({ ok: false, error: "unreachable" }));
+ ).catch(() => ({ ok: false, error: t("provider.err_unreachable") }));
setSaving(false);
if (!result.ok || !result.provider) {
- setError(result.error || "Couldn’t add provider.");
+ setError(result.error || t("manage.custom_add_failed"));
return;
}
await onCreated(result.provider);
};
return (
- <div className={CARD + " p-4 max-w-xl"} data-testid="set-custom-provider-form">
- <div className="text-[15px] font-semibold">Add OpenAI-compatible provider</div>
- <p className="text-[12px] text-muted mt-1 leading-relaxed">
- This provider uses Chat Completions with Bearer authentication. Use HTTPS unless the gateway is local; you’ll add its model IDs manually next.
- </p>
- <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-title">Provider name</label>
- <input id="custom-provider-title" className={input} value={title} placeholder="OpenRouter" onChange={(e) => setTitle(e.target.value)} />
- <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-route">Route prefix</label>
- <input id="custom-provider-route" className={input} value={name} placeholder="openrouter" spellCheck={false} autoCapitalize="none" onChange={(e) => setName(e.target.value.toLowerCase())} />
- <p className="text-[11.5px] text-faint mt-1">Models will be selected as <code>openrouter:model-id</code>.</p>
- <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-endpoint">Endpoint</label>
- <input id="custom-provider-endpoint" className={input} value={baseUrl} placeholder="https://…/v1" spellCheck={false} autoCapitalize="none" onChange={(e) => setBaseUrl(e.target.value)} />
- <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-key">API key</label>
- <input id="custom-provider-key" className={input} type="password" value={apiKey} placeholder="…" autoComplete="off" onChange={(e) => setApiKey(e.target.value)} />
- {error && <div className="text-[12.5px] text-warnInk mt-3">{error}</div>}
- <div className="flex gap-2 mt-4">
- <button className={BTN_ACCENT} disabled={saving} onClick={() => void save()}>{saving ? "Adding…" : "Add provider"}</button>
- <button className={BTN_BORDERED} onClick={onCancel}>Cancel</button>
+ <div className={CARD + " p-4 max-w-xl mb-6"} data-testid="set-custom-provider-form">
+ <div className="text-body font-semibold">{t("manage.custom_add_title")}</div>
+ <p className="text-meta text-muted mt-1 leading-relaxed">{t("manage.custom_add_desc")}</p>
+ <label className={label} htmlFor="custom-provider-title">{t("manage.custom_name_label")}</label>
+ <input
+ id="custom-provider-title"
+ className={input}
+ value={title}
+ placeholder={t("manage.custom_name_placeholder")}
+ data-testid="custom-provider-title"
+ onChange={(e) => {
+ setTitle(e.target.value);
+ if (!nameTouched) setName(routePrefixFor(e.target.value));
+ }}
+ />
+ <label className={label} htmlFor="custom-provider-route">{t("manage.custom_route_label")}</label>
+ <input
+ id="custom-provider-route"
+ className={input + " font-mono"}
+ value={prefix}
+ spellCheck={false}
+ autoCapitalize="none"
+ data-testid="custom-provider-route"
+ onChange={(e) => {
+ setNameTouched(true);
+ setName(e.target.value.toLowerCase().replace(/[^a-z0-9_-]/g, ""));
+ }}
+ />
+ <p className="text-meta text-faint mt-1">{t("manage.custom_route_hint", { prefix: prefix || "acme" })}</p>
+ <label className={label} htmlFor="custom-provider-endpoint">{t("manage.custom_endpoint_label")}</label>
+ <input
+ id="custom-provider-endpoint"
+ className={input}
+ value={baseUrl}
+ placeholder="https://…/v1"
+ spellCheck={false}
+ autoCapitalize="none"
+ data-testid="custom-provider-endpoint"
+ onChange={(e) => setBaseUrl(e.target.value)}
+ />
+ <p className="text-meta text-faint mt-1">{t("manage.custom_endpoint_help")}</p>
+ <label className={label} htmlFor="custom-provider-key">{t("manage.custom_key_label")}</label>
+ <input
+ id="custom-provider-key"
+ className={input}
+ type="password"
+ value={apiKey}
+ autoComplete="off"
+ data-testid="custom-provider-key"
+ onChange={(e) => setApiKey(e.target.value)}
+ />
+ <div className="mt-3 min-h-[19px] text-ui">{error && <span className="text-warnInk" data-testid="custom-provider-error">{error}</span>}</div>
+ <div className="flex gap-2 mt-1">
+ <button
+ className={BTN_ACCENT}
+ disabled={saving || !title.trim() || !prefix || !baseUrl.trim() || !apiKey.trim()}
+ data-testid="custom-provider-add"
+ onClick={() => void save()}
+ >
+ {saving ? t("manage.custom_adding") : t("manage.custom_add_btn")}
+ </button>
+ <button className={BTN_BORDERED} onClick={onCancel} data-testid="custom-provider-cancel">{t("manage.custom_cancel")}</button>
</div>
</div>
);
diff --git a/surfaces/gui/src/components/models/ProviderGroups.tsx b/surfaces/gui/src/components/models/ProviderGroups.tsx
index 5aa26bbd..819fe011 100644
--- a/surfaces/gui/src/components/models/ProviderGroups.tsx
+++ b/surfaces/gui/src/components/models/ProviderGroups.tsx
@@ -44,7 +44,7 @@ export function ProviderGroups({
ps: ProviderSetupState;
tp: string;
models: string[]; // the picker's models, for the count on each card
- onAddCustom?: () => void; // Settings: the "Custom provider" card at the end of the API-keys group
+ onAddCustom?: () => void; // Settings: the permanent "Add an OpenAI-compatible provider" box, last in the API-keys group
}) {
const { t } = useTranslation();
const [query, setQuery] = useState("");
@@ -112,7 +112,9 @@ export function ProviderGroups({
{/* A long group (API keys) shows two rows, then a "Show N more" line expands it in place. */}
<div className="grid grid-cols-2 xl:grid-cols-3 gap-3" data-testid={`provider-grid-${kind}`}>
{(expanded.has(kind) || q ? cards : cards.slice(0, FOLD)).map(cardFor)}
- {kind === "api_key" && onAddCustom && (expanded.has(kind) || q || cards.length <= FOLD) && (
+ {/* The add box stays whatever the fold or the search shows: saving it makes a
+ new card named by the user, and the box remains for the next one. */}
+ {kind === "api_key" && onAddCustom && (
<button
className={card + " border-dashed bg-transparent text-muted hover:text-ink"}
data-testid={`${tp}-provider-custom-add`}
diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.json
index ad77da5d..02d7a797 100644
--- a/surfaces/gui/src/locales/en.json
+++ b/surfaces/gui/src/locales/en.json
@@ -1349,7 +1349,25 @@
"remove_key_confirm": "Remove the {{title}} key from this computer?",
"remove_provider": "Remove provider…",
"remove_provider_confirm": "Remove the {{title}} provider and its key from this computer?",
- "custom_provider_card": "Custom provider",
+ "custom_provider_card": "Add an OpenAI-compatible provider",
+ "custom_add_title": "Add an OpenAI-compatible provider",
+ "custom_add_desc": "Any server that speaks the OpenAI chat API with a Bearer key — a gateway, a proxy, a vendor not listed here. HTTPS, except on localhost or a private address. You add its model ids next.",
+ "custom_name_label": "Name",
+ "custom_name_placeholder": "Acme Gateway",
+ "custom_route_label": "Route prefix",
+ "custom_route_hint": "Models are selected as {{prefix}}:<model-id>. Set it before the first save; a built-in provider's name cannot be used.",
+ "custom_endpoint_label": "Endpoint",
+ "custom_endpoint_help": "The base URL, usually ending in /v1.",
+ "custom_key_label": "API key",
+ "custom_add_btn": "Add provider",
+ "custom_adding": "Adding…",
+ "custom_cancel": "Cancel",
+ "custom_add_failed": "Couldn't add the provider.",
+ "custom_models_help": "Type the model ids your server accepts, or fetch its list. Ticked models show in the composer's picker.",
+ "custom_fetch_models": "Fetch from server",
+ "custom_fetching": "Fetching…",
+ "custom_fetched_count": "{{count}} models listed — tick the ones you want.",
+ "custom_fetched_none": "The server listed no models.",
"signin_unlocks": "Sign-in unlocks the one-click {{title}} connect — or connect manually below.",
"tool_asks_approval": "{{name}} · {{kind}} · asks approval",
"tools_exposed": "Tools exposed to OpenWorker",
diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.json
index 1d03f8c5..dcbc7cdf 100644
--- a/surfaces/gui/src/locales/zh.json
+++ b/surfaces/gui/src/locales/zh.json
@@ -1332,7 +1332,25 @@
"remove_key_confirm": "从本机移除 {{title}} 密钥?",
"remove_provider": "移除提供商…",
"remove_provider_confirm": "从本机移除 {{title}} 提供商及其密钥?",
- "custom_provider_card": "自定义提供商",
+ "custom_provider_card": "添加 OpenAI 兼容提供商",
+ "custom_add_title": "添加 OpenAI 兼容提供商",
+ "custom_add_desc": "任何使用 Bearer 密钥、支持 OpenAI 聊天 API 的服务器——网关、代理或未列出的供应商。需使用 HTTPS,localhost 或内网地址除外。下一步添加其模型 ID。",
+ "custom_name_label": "名称",
+ "custom_name_placeholder": "Acme Gateway",
+ "custom_route_label": "路由前缀",
+ "custom_route_hint": "模型将以 {{prefix}}:<model-id> 的形式选择。请在首次保存前设定;不能使用内置提供商的名称。",
+ "custom_endpoint_label": "端点",
+ "custom_endpoint_help": "基础 URL,通常以 /v1 结尾。",
+ "custom_key_label": "API 密钥",
+ "custom_add_btn": "添加提供商",
+ "custom_adding": "添加中…",
+ "custom_cancel": "取消",
+ "custom_add_failed": "无法添加该提供商。",
+ "custom_models_help": "输入服务器接受的模型 ID,或获取其列表。勾选的模型会出现在编辑器的选择器中。",
+ "custom_fetch_models": "从服务器获取",
+ "custom_fetching": "获取中…",
+ "custom_fetched_count": "列出了 {{count}} 个模型——勾选你需要的。",
+ "custom_fetched_none": "服务器未列出任何模型。",
"signin_unlocks": "登录即可解锁 {{title}} 一键连接 —— 或在下方手动连接。",
"tool_asks_approval": "{{name}} · {{kind}} · 需审批",
"tools_exposed": "向 OpenWorker 提供的工具",
diff --git a/tests/test_provider_router.py b/tests/test_provider_router.py
index 3781f449..626d2480 100644
--- a/tests/test_provider_router.py
+++ b/tests/test_provider_router.py
@@ -460,6 +460,62 @@ def test_custom_provider_requires_safe_route_and_complete_config(tmp_path, monke
)["ok"]
+def test_custom_provider_slug_cannot_shadow_a_built_in(tmp_path, monkeypatch):
+ """A custom route prefix is the model id's namespace; a built-in's name is taken."""
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ res = mgr.create_custom_provider(
+ "groq", "My Groq", {"api_key": "x", "base_url": "https://api.groq.com/openai/v1"}
+ )
+ assert res["ok"] is False and "already in use" in res["error"]
+ assert all(not p.get("is_custom") for p in mgr.get_providers() if p["name"] == "groq")
+
+
+def test_custom_provider_key_change_reaches_the_router(tmp_path, monkeypatch):
+ """Re-saving a custom provider's key rebuilds its client (the adopt step used to look
+ the descriptor up without the store and skip the refresh for custom routes)."""
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ assert mgr.create_custom_provider(
+ "acme", "Acme Gateway", {"api_key": "acme-1", "base_url": "https://llm.acme.example/v1"}
+ )["ok"]
+ assert mgr.provider._client_for("acme:some-model")._api_key == "acme-1"
+ assert mgr.set_provider("acme", {"api_key": "acme-2"})["ok"]
+ assert mgr.provider._client_for("acme:some-model")._api_key == "acme-2"
+
+
+def test_custom_provider_lists_models_from_its_server(tmp_path, monkeypatch):
+ """"Fetch from server" reads GET /models with the saved key; a server without the
+ listing comes back as a note, not a failure."""
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ assert mgr.create_custom_provider(
+ "acme", "Acme Gateway", {"api_key": "acme-test", "base_url": "https://llm.acme.example/v1"}
+ )["ok"]
+ seen = {}
+
+ def fake_get(url, headers=None, timeout=None):
+ seen.update(url=url, headers=headers or {})
+ return SimpleNamespace(status_code=200, json=lambda: {"data": [{"id": "acme-large"}, {"id": "acme-small"}]})
+
+ monkeypatch.setattr("httpx.get", fake_get)
+ got = mgr.local_model_facts("acme")
+ assert [r["model"] for r in got["models"]] == ["acme:acme-large", "acme:acme-small"]
+ assert got["models"][0]["name"] == "acme-large" and "error" not in got
+ assert seen["url"] == "https://llm.acme.example/v1/models"
+ assert seen["headers"]["Authorization"] == "Bearer acme-test"
+
+ monkeypatch.setattr("httpx.get", lambda *a, **k: SimpleNamespace(status_code=404, json=lambda: {}))
+ got = mgr.local_model_facts("acme")
+ assert got["models"] == [] and "/models" in got["error"]
+
+
def test_custom_provider_verify_allows_missing_models_endpoint(tmp_path, monkeypatch):
monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
from coworker.server.manager import SessionManager