Skip to content
Python

Add custom OpenAI-compatible providers

Mumit Khane9777cbb1baa
diff --git a/README.md b/README.md
index b5281a55..c6db7374 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,8 @@ 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.
+
## Privacy
OpenWorker is local-first. Everything lives on your machine: the agent loop, your conversations, connector tokens, and model keys - all in the app's local secret store. The only cloud piece is a small service that brokers OAuth handshakes for connectors. You can always use the App without signing-in - use the connectors via manually-created credentials/API-keys.
diff --git a/coworker/providers/__init__.py b/coworker/providers/__init__.py
index d38da557..d154b4d1 100644
--- a/coworker/providers/__init__.py
+++ b/coworker/providers/__init__.py
@@ -19,6 +19,8 @@ from .registry import (
descriptor_configured,
detect_provider,
get_descriptor,
+ is_custom_provider,
+ is_removed_custom_provider,
provider_descriptors,
provider_names,
verify_provider_key,
@@ -47,6 +49,8 @@ __all__ = [
"provider_descriptors",
"provider_names",
"get_descriptor",
+ "is_custom_provider",
+ "is_removed_custom_provider",
"build_provider_client",
"descriptor_configured",
"detect_provider",
diff --git a/coworker/providers/registry.py b/coworker/providers/registry.py
index 6dc5a6df..32f39efa 100644
--- a/coworker/providers/registry.py
+++ b/coworker/providers/registry.py
@@ -31,6 +31,9 @@ from .openai_responses import OpenAIResponsesProvider
from .vertex_provider import VertexProvider
DEFAULT_OLLAMA_URL = "http://localhost:11434"
+# The index deliberately lives in the SecretStore too: it names profiles which contain
+# credentials, and keeping the two together makes a future secure-store backend a drop-in.
+CUSTOM_PROVIDERS_PROFILE = "providers:custom"
@dataclass(frozen=True)
@@ -380,6 +383,50 @@ def _responses_compat(
)
+def _custom_provider_descriptor(name: str, title: str) -> ProviderDescriptor:
+ """Descriptor synthesized for a user-defined OpenAI-compatible endpoint.
+
+ Unlike the built-ins there is no catalog or capability claim here. The endpoint and
+ bearer key are required; model ids are supplied separately by the user.
+ """
+ return ProviderDescriptor(
+ name=name,
+ title=title,
+ needs_key=True,
+ fields=[
+ ProviderField("api_key", f"{title} API key", secret=True),
+ ProviderField(
+ "base_url",
+ "Endpoint",
+ required=True,
+ placeholder="https://…/v1",
+ help="An HTTPS OpenAI-compatible API base URL ending in /v1. HTTP is allowed only for local gateways.",
+ ),
+ ],
+ build=_openai_compat(title, ""),
+ blurb="Uses the standard OpenAI Chat Completions API. Add model IDs manually below.",
+ )
+
+
+def _disabled_custom_provider_descriptor(name: str, title: str) -> ProviderDescriptor:
+ """Keep a removed route recognizable so old sessions fail closed, never reroute."""
+
+ def build(profile: dict[str, Any], secrets: Any) -> ProviderClient:
+ raise RuntimeError(
+ f"{title} was removed from Settings ▸ Models. Configure that provider again "
+ "before continuing this session."
+ )
+
+ return ProviderDescriptor(
+ name=name,
+ title=title,
+ needs_key=True,
+ fields=[],
+ build=build,
+ blurb="Removed custom provider.",
+ )
+
+
DESCRIPTORS: list[ProviderDescriptor] = [
ProviderDescriptor(
name="openai",
@@ -894,23 +941,78 @@ DESCRIPTORS: list[ProviderDescriptor] = [
_BY_NAME = {d.name: d for d in DESCRIPTORS}
-def provider_descriptors() -> list[ProviderDescriptor]:
- return list(DESCRIPTORS)
-
-
-def provider_names() -> list[str]:
- return [d.name for d in DESCRIPTORS]
-
-
-def get_descriptor(name: str) -> Optional[ProviderDescriptor]:
- return _BY_NAME.get(name)
+def _custom_provider_titles(secrets: Any = None) -> dict[str, str]:
+ """Return the validated custom-provider index without exposing credentials."""
+ if secrets is None:
+ return {}
+ raw = secrets.get(CUSTOM_PROVIDERS_PROFILE) or {}
+ providers = raw.get("providers") if isinstance(raw, dict) else None
+ if not isinstance(providers, dict):
+ return {}
+ return {
+ name: title
+ for name, title in providers.items()
+ if isinstance(name, str)
+ and isinstance(title, str)
+ and name not in _BY_NAME
+ and title.strip()
+ }
+
+
+def _removed_custom_provider_titles(secrets: Any = None) -> dict[str, str]:
+ """Routes kept as tombstones after deletion to protect existing sessions."""
+ if secrets is None:
+ return {}
+ raw = secrets.get(CUSTOM_PROVIDERS_PROFILE) or {}
+ removed = raw.get("removed") if isinstance(raw, dict) else None
+ if not isinstance(removed, dict):
+ return {}
+ return {
+ name: title
+ for name, title in removed.items()
+ if isinstance(name, str)
+ and isinstance(title, str)
+ and name not in _BY_NAME
+ and title.strip()
+ }
+
+
+def is_custom_provider(name: str, secrets: Any = None) -> bool:
+ return name in _custom_provider_titles(secrets)
+
+
+def is_removed_custom_provider(name: str, secrets: Any = None) -> bool:
+ return name in _removed_custom_provider_titles(secrets)
+
+
+def provider_descriptors(secrets: Any = None) -> list[ProviderDescriptor]:
+ custom = [
+ _custom_provider_descriptor(name, title)
+ for name, title in _custom_provider_titles(secrets).items()
+ ]
+ return [*DESCRIPTORS, *custom]
+
+
+def provider_names(secrets: Any = None) -> list[str]:
+ return [d.name for d in provider_descriptors(secrets)]
+
+
+def get_descriptor(name: str, secrets: Any = None) -> Optional[ProviderDescriptor]:
+ builtin = _BY_NAME.get(name)
+ if builtin is not None:
+ return builtin
+ title = _custom_provider_titles(secrets).get(name)
+ if title:
+ return _custom_provider_descriptor(name, title)
+ title = _removed_custom_provider_titles(secrets).get(name)
+ return _disabled_custom_provider_descriptor(name, title) if title else None
def build_provider_client(
name: str, profile: dict[str, Any], secrets: Any
) -> ProviderClient:
"""Build a `ProviderClient` for `name` from its stored profile. Unknown → OpenAI default."""
- descriptor = _BY_NAME.get(name) or _BY_NAME["openai"]
+ descriptor = get_descriptor(name, secrets) or _BY_NAME["openai"]
return descriptor.build(profile or {}, secrets)
@@ -1180,6 +1282,7 @@ def verify_provider_key(
base_url: Optional[str] = None,
fields: Optional[dict[str, Any]] = None,
timeout: float = 10.0,
+ descriptor: Optional[ProviderDescriptor] = None,
) -> dict[str, Any]:
"""Validate a provider's credentials with one cheap call — usually list models.
@@ -1190,7 +1293,7 @@ def verify_provider_key(
"""
import httpx
- d = _BY_NAME.get(name) or _BY_NAME["openai"]
+ d = descriptor or _BY_NAME.get(name) or _BY_NAME["openai"]
key = (api_key or "").strip()
if d.auth == "oauth":
# OAuth providers verify from their stored tokens (needs the SecretStore),
@@ -1306,6 +1409,14 @@ def verify_provider_key(
if resp.status_code < 300:
return {"ok": True}
+ if resp.status_code in (404, 405) and d.name not in _BY_NAME:
+ # Chat Completions compatibility does not require the optional model-list
+ # endpoint. The gateway was reached, so do not call a usable custom route
+ # invalid merely because it cannot provide a catalog.
+ return {
+ "ok": True,
+ "warning": "Endpoint reached, but it does not expose /models. Add a model ID and try a chat to finish checking it.",
+ }
if resp.status_code in (401, 403):
if name == "ollama":
return {"ok": False, "error": "Server rejected the request."}
diff --git a/coworker/providers/router.py b/coworker/providers/router.py
index c2c56c47..4a6d7f19 100644
--- a/coworker/providers/router.py
+++ b/coworker/providers/router.py
@@ -51,7 +51,7 @@ class ProviderRouter(ProviderClient):
"""
if ":" in model:
prefix = model.split(":", 1)[0]
- if get_descriptor(prefix) is not None:
+ if get_descriptor(prefix, getattr(self, "_secrets", None)) is not None:
return prefix
return self._default
@@ -68,14 +68,14 @@ class ProviderRouter(ProviderClient):
return client
@staticmethod
- def _bare(model: str) -> str:
+ def _bare(model: str, secrets: Any = None) -> str:
"""Strip a KNOWN provider prefix; the underlying SDK wants the bare model name. A model
whose first segment isn't a provider (e.g. `qwen2.5-coder:32b` — a version tag, not a
prefix) is returned unchanged, so the colon isn't mistaken for a provider separator.
"""
if ":" in model:
prefix, rest = model.split(":", 1)
- if get_descriptor(prefix) is not None:
+ if get_descriptor(prefix, secrets) is not None:
return rest
return model
@@ -98,7 +98,7 @@ class ProviderRouter(ProviderClient):
):
self._note_use(model)
return self._client_for(model).complete(
- model=self._bare(model), messages=messages, tools=tools, **settings
+ model=self._bare(model, self._secrets), messages=messages, tools=tools, **settings
)
def stream(
@@ -111,7 +111,7 @@ class ProviderRouter(ProviderClient):
):
self._note_use(model)
return self._client_for(model).stream(
- model=self._bare(model), messages=messages, tools=tools, **settings
+ model=self._bare(model, self._secrets), messages=messages, tools=tools, **settings
)
def capabilities(self, model: str):
diff --git a/coworker/server/app.py b/coworker/server/app.py
index c4d4f672..d32b38b5 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -2393,6 +2393,13 @@ def create_app(manager: SessionManager) -> FastAPI:
return manager.set_provider(name, (body or {}).get("fields"))
return await asyncio.to_thread(manager.set_provider, name, (body or {}).get("fields"))
+ @app.post("/v1/providers/custom")
+ def providers_custom_create(body: dict) -> dict[str, Any]:
+ body = body or {}
+ return manager.create_custom_provider(
+ body.get("name", ""), body.get("title", ""), body.get("fields")
+ )
+
@app.delete("/v1/providers/{name}")
async def providers_remove(name: str) -> dict[str, Any]:
if name == "openrouter-account":
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 12a4939f..8b75a8ea 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -8,6 +8,7 @@ sessions span folders.
from __future__ import annotations
import asyncio
+import ipaddress
import threading
import json
import logging
@@ -21,6 +22,7 @@ import time
import uuid
from pathlib import Path
from typing import Any, Optional
+from urllib.parse import urlsplit
from .. import model_config as _model_config
from ..agent import build_engine
@@ -84,9 +86,12 @@ from ..providers import (
ProviderRouter,
descriptor_configured,
get_descriptor,
+ is_custom_provider,
+ is_removed_custom_provider,
provider_descriptors,
verify_provider_key,
)
+from ..providers.registry import CUSTOM_PROVIDERS_PROFILE
from ..secrets import SecretStore, state_dir
from ..sessions import SessionRecord, usage_totals
from ..teams import Actor as TeamActor
@@ -115,6 +120,28 @@ _SCOPES = {s.value for s in Scope}
logger = logging.getLogger("coworker.manager")
+def _custom_endpoint_error(url: str) -> Optional[str]:
+ """Allow HTTPS everywhere; plaintext HTTP only for an explicitly local gateway."""
+ try:
+ parsed = urlsplit((url or "").strip())
+ except ValueError:
+ return "Enter a valid HTTPS endpoint."
+ if parsed.scheme == "https" and parsed.hostname:
+ return None
+ if parsed.scheme != "http" or not parsed.hostname:
+ return "Endpoint must be an HTTPS URL (for example, https://gateway.example/v1)."
+ host = parsed.hostname.lower()
+ if host == "localhost":
+ return None
+ try:
+ address = ipaddress.ip_address(host)
+ except ValueError:
+ return "HTTP endpoints are allowed only for localhost or a private IP address."
+ if address.is_loopback or address.is_private:
+ return None
+ return "HTTP endpoints are allowed only for localhost or a private IP address."
+
+
def _grants_of(engine) -> dict[str, Any]:
"""The engine's session-scoped "Always allow" approvals, in persistable shape."""
tools = sorted(getattr(engine.permissions, "session_allow_tools", None) or ())
@@ -4162,7 +4189,7 @@ class SessionManager:
non-secret field values (e.g. the Ollama base URL) ARE returned so the form can prefill.
"""
out: list[dict[str, Any]] = []
- for d in provider_descriptors():
+ for d in provider_descriptors(self.secrets):
profile = self.secrets.get(f"provider:{d.name}") or {}
configured = descriptor_configured(d, profile)
values = {
@@ -4189,6 +4216,7 @@ class SessionManager:
"last_used_at": (self._prefs.get("provider_last_used") or {}).get(
d.name
),
+ "is_custom": is_custom_provider(d.name, self.secrets),
}
if d.kind == "local":
# A keyless server is "connected" when it answers (cached probes), not
@@ -4207,6 +4235,51 @@ class SessionManager:
out.append(row)
return out
+ def create_custom_provider(
+ self, name: str, title: str, fields: Optional[dict[str, Any]]
+ ) -> dict[str, Any]:
+ """Create a named OpenAI-compatible provider, then save its first credentials.
+
+ The short slug is the stable model-route prefix (``slug:model-id``), so it is
+ deliberately immutable and restricted to a transport-safe subset.
+ """
+ name = (name or "").strip().lower()
+ title = (title or "").strip()
+ if not re.fullmatch(r"[a-z][a-z0-9_-]{0,31}", name):
+ return {
+ "ok": False,
+ "error": "Route prefix must start with a letter and use only lowercase letters, numbers, - or _.",
+ }
+ if not title or len(title) > 80:
+ return {"ok": False, "error": "Enter a provider name (up to 80 characters)."}
+ if get_descriptor(name) is not None or is_custom_provider(name, self.secrets):
+ return {"ok": False, "error": "That route prefix is already in use."}
+ fields = fields or {}
+ base_url = str(fields.get("base_url") or "").strip()
+ endpoint_error = _custom_endpoint_error(base_url)
+ if endpoint_error:
+ return {"ok": False, "error": endpoint_error}
+ if not str(fields.get("api_key") or "").strip():
+ return {"ok": False, "error": "Enter an API key."}
+
+ index = dict(self.secrets.get(CUSTOM_PROVIDERS_PROFILE) or {})
+ providers = dict(index.get("providers") or {})
+ removed = dict(index.get("removed") or {})
+ previous_removed = dict(removed)
+ providers[name] = title
+ removed.pop(name, None) # re-creating a route clears its fail-closed tombstone
+ self.secrets.put(
+ CUSTOM_PROVIDERS_PROFILE, {"providers": providers, "removed": removed}
+ )
+ saved = self.set_provider(name, fields)
+ if not saved.get("ok"):
+ providers.pop(name, None)
+ self.secrets.put(
+ CUSTOM_PROVIDERS_PROFILE,
+ {"providers": providers, "removed": previous_removed},
+ )
+ return saved
+
def pick_native_folder(self) -> dict[str, Any]:
"""Open the OS folder picker FROM THE SIDECAR — the browser GUI can't obtain absolute
paths from web file dialogs, but the sidecar is local and can (the desktop shell uses
@@ -4303,9 +4376,11 @@ class SessionManager:
) -> dict[str, Any]:
"""Store a provider's config in its `provider:<name>` SecretStore profile and rebuild
its cached client. Merges provided fields into any existing profile."""
- d = get_descriptor(name)
+ d = get_descriptor(name, self.secrets)
if d is None:
return {"ok": False, "error": f"unknown provider: {name}"}
+ if is_removed_custom_provider(name, self.secrets):
+ return {"ok": False, "error": "provider was removed; create it again first"}
fields = fields or {}
profile = dict(self.secrets.get(f"provider:{name}") or {})
for f in d.fields:
@@ -4321,6 +4396,10 @@ class SessionManager:
missing = [f.label for f in d.fields if f.required and not profile.get(f.key)]
if missing:
return {"ok": False, "error": "missing: " + ", ".join(missing)}
+ if is_custom_provider(name, self.secrets):
+ endpoint_error = _custom_endpoint_error(str(profile.get("base_url") or ""))
+ if endpoint_error:
+ return {"ok": False, "error": endpoint_error}
# A (re)pasted key stamps its save date — Settings shows "key added <date>" so stale
# keys are visible. Endpoint-only saves keep the original stamp.
if isinstance(fields.get("api_key"), str) and fields["api_key"].strip():
@@ -4366,7 +4445,7 @@ class SessionManager:
"""Forget a provider's stored config (Settings ▸ Models "Remove key"). The whole
`provider:<name>` profile goes — key, endpoint, key_set_at — so the provider reads
as never configured. Curated models stay; they just gray out until a new key."""
- d = get_descriptor(name)
+ d = get_descriptor(name, self.secrets)
if d is None:
return {"ok": False, "error": f"unknown provider: {name}"}
env_var = d.env_key if (d.env_key and os.environ.get(d.env_key)) else None
@@ -4385,6 +4464,31 @@ class SessionManager:
),
}
self.secrets.delete(f"provider:{name}")
+ if is_custom_provider(name, self.secrets):
+ index = dict(self.secrets.get(CUSTOM_PROVIDERS_PROFILE) or {})
+ providers = dict(index.get("providers") or {})
+ removed = dict(index.get("removed") or {})
+ title = providers.pop(name, d.title)
+ removed[name] = title
+ self.secrets.put(
+ CUSTOM_PROVIDERS_PROFILE,
+ {"providers": providers, "removed": removed},
+ )
+ # A deleted custom route must not remain selectable and accidentally fall
+ # through to the default OpenAI provider as an unknown ``prefix:model``.
+ prefix = name + ":"
+ self._prefs["models"] = [
+ m for m in self._prefs.get("models", []) if not str(m).startswith(prefix)
+ ]
+ self._prefs["hidden_models"] = [
+ m
+ for m in self._prefs.get("hidden_models", [])
+ if not str(m).startswith(prefix)
+ ]
+ if str(self.model).startswith(prefix):
+ self.model = "gpt-5.6-sol"
+ self._prefs["default_model"] = self.model
+ self._save_prefs()
self._refresh_provider(name)
out: dict[str, Any] = {"ok": True, "provider": name}
if env_var:
@@ -4453,7 +4557,7 @@ class SessionManager:
a field blank (e.g. testing an already-configured provider)."""
import os
- d = get_descriptor(name)
+ d = get_descriptor(name, self.secrets)
if d is None:
return {"ok": False, "error": f"unknown provider: {name}"}
if d.auth == "oauth":
@@ -4482,20 +4586,27 @@ class SessionManager:
missing = [f.label for f in d.fields if f.required and not merged.get(f.key)]
if missing:
return {"ok": False, "error": "missing: " + ", ".join(missing)}
+ # A verification call sends the key to the supplied endpoint too. Apply the
+ # same transport policy as Save so an unsaved edit cannot accidentally
+ # send a credential over plaintext to a remote host.
+ if is_custom_provider(name, self.secrets):
+ endpoint_error = _custom_endpoint_error(merged.get("base_url", ""))
+ if endpoint_error:
+ return {"ok": False, "error": endpoint_error}
return verify_provider_key(
- name, api_key=api_key, base_url=merged.get("base_url", ""), fields=merged
+ name, api_key=api_key, base_url=merged.get("base_url", ""), fields=merged, descriptor=d
)
def _model_provider(self, model: str) -> str:
"""The provider a model string routes to (known `prefix:` or the OpenAI default)."""
if ":" in (model or ""):
prefix = model.split(":", 1)[0]
- if get_descriptor(prefix) is not None:
+ if get_descriptor(prefix, self.secrets) is not None:
return prefix
return "openai"
def _provider_configured(self, name: str) -> bool:
- d = get_descriptor(name)
+ d = get_descriptor(name, self.secrets)
if d is None:
return False
return descriptor_configured(d, self.secrets.get(f"provider:{name}") or {})
diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.ts
index 1a9cf81b..fe5b0df1 100644
--- a/surfaces/gui/src/api.ts
+++ b/surfaces/gui/src/api.ts
@@ -2517,6 +2517,7 @@ export interface ProviderInfo {
// How Models & Keys groups it: a server on the user's own hardware, a plan signed
// into, or an API key. Absent on an older backend → treated as an API key.
kind?: "local" | "subscription" | "api_key";
+ is_custom?: boolean; // user-created OpenAI-compatible provider
// Local servers only: whether the server answers right now (cached probe).
alive?: boolean;
signed_in?: boolean;
@@ -2737,6 +2738,20 @@ export async function setProvider(
return res.json();
}
+/** Create a named, user-configured OpenAI-compatible provider. */
+export async function createCustomProvider(
+ name: string,
+ title: string,
+ fields: Record<string, string>,
+): Promise<{ ok: boolean; error?: string; provider?: string }> {
+ const res = await fetch(`${httpBase()}/v1/providers/custom`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ name, title, fields }),
+ });
+ return res.json();
+}
+
/** Forget a provider's stored config (Settings ▸ Models "Remove key…"). */
export async function removeProvider(name: string): Promise<{ ok: boolean; error?: string }> {
const res = await fetch(`${httpBase()}/v1/providers/${encodeURIComponent(name)}`, {
@@ -2749,7 +2764,7 @@ export async function removeProvider(name: string): Promise<{ ok: boolean; error
export async function verifyProvider(
name: string,
fields: Record<string, string>,
-): Promise<{ ok: boolean; error?: string }> {
+): Promise<{ ok: boolean; error?: string; warning?: string }> {
const res = await fetch(`${httpBase()}/v1/providers/verify`, {
method: "POST",
headers: { "Content-Type": "application/json" },
diff --git a/surfaces/gui/src/components/ManageTabs.test.tsx b/surfaces/gui/src/components/ManageTabs.test.tsx
new file mode 100644
index 00000000..39f4072d
--- /dev/null
+++ b/surfaces/gui/src/components/ManageTabs.test.tsx
@@ -0,0 +1,92 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { ModelsTab } from "./ManageTabs";
+
+afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+});
+
+it("creates a custom provider and opens its manual-model configuration", async () => {
+ 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,
+ });
+ if (url.includes("/v1/providers/custom") && method === "POST") {
+ created = true;
+ return { json: async () => ({ ok: true, provider: "openrouter" }) } 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: [],
+ recommended_model: "gpt-5.6-sol",
+ },
+ ];
+ if (created) {
+ providers.push({
+ name: "openrouter",
+ title: "OpenRouter",
+ needs_key: true,
+ fields: [
+ { key: "api_key", label: "OpenRouter 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 }) } as Response;
+ }),
+ );
+
+ 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" }));
+
+ await waitFor(() => {
+ 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" },
+ },
+ });
+ });
+ expect((await screen.findByTestId("set-field-base_url") as HTMLInputElement).value).toBe(
+ "https://openrouter.ai/api/v1",
+ );
+});
diff --git a/surfaces/gui/src/components/ManageTabs.tsx b/surfaces/gui/src/components/ManageTabs.tsx
index 920b7f68..96f46a9c 100644
--- a/surfaces/gui/src/components/ManageTabs.tsx
+++ b/surfaces/gui/src/components/ManageTabs.tsx
@@ -6,6 +6,7 @@ import {
connectConnector,
connectManaged,
connectMcpBacked,
+ createCustomProvider,
disallowUser,
getSettings,
getSubscriptions,
@@ -47,6 +48,7 @@ const relTime = (epoch?: number | null): string | null => {
// when Settings/Activity became full-page surfaces): ModelsTab → Settings ▸ Models; ConnectorsTab →
// Integrations ▸ Connectors (the MCP tab retired into the Connectors page, UX-034).
const SEC_H = "text-label text-faint font-medium";
+const CARD = "rounded-xl2 border border-line bg-panel";
const BTN_BORDERED =
"text-ui px-3 py-1.5 rounded-lg border border-line bg-paper hover:border-lineStrong shrink-0";
const BTN_ACCENT = "text-ui px-3 py-1.5 rounded-lg bg-accent text-white shrink-0 disabled:opacity-50";
@@ -78,10 +80,11 @@ export function ProviderKeyFooter({
className="text-ui text-danger/80 hover:text-danger hover:underline underline-offset-2"
data-testid="set-remove-key"
onClick={() => {
- if (window.confirm(t("manage.remove_key_confirm", { title: info?.title || "" }))) onRemove();
+ const key = info?.is_custom ? "manage.remove_provider_confirm" : "manage.remove_key_confirm";
+ if (window.confirm(t(key, { title: info?.title || "" }))) onRemove();
}}
>
- {t("manage.remove_key")}
+ {t(info?.is_custom ? "manage.remove_provider" : "manage.remove_key")}
</button>
);
}
@@ -97,6 +100,8 @@ export function ModelsTab() {
// The Pick a model dialog (UX-055): "" closed, "+" picking, else the model to configure.
const [dialog, setDialog] = useState<string>("");
const [settingsError, setSettingsError] = useState(false);
+ const [addingCustom, setAddingCustom] = useState(false);
+ const [openCustom, setOpenCustom] = useState<string | null>(null);
const refreshSettings = () => {
setSettingsError(false);
getSettings()
@@ -118,6 +123,13 @@ export function ModelsTab() {
} catch { /* private window */ }
}, []);
+ useEffect(() => {
+ if (openCustom && ps.providers.some((p) => p.name === openCustom)) {
+ setOpenCustom(null);
+ ps.openProvider(openCustom);
+ }
+ }, [openCustom, ps.providers]);
+
// #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) {
@@ -152,7 +164,19 @@ export function ModelsTab() {
if (ps.sel === null) {
return (
<div>
- <ProviderGroups ps={ps} tp="set" models={settings.models} />
+ {addingCustom ? (
+ <CustomProviderForm
+ onCancel={() => setAddingCustom(false)}
+ onCreated={async (name) => {
+ setAddingCustom(false);
+ setOpenCustom(name);
+ await ps.refreshProviders();
+ refreshSettings();
+ }}
+ />
+ ) : (
+ <ProviderGroups ps={ps} tp="set" models={settings.models} onAddCustom={() => setAddingCustom(true)} />
+ )}
<ComposerPickerCard settings={settings} providers={ps.providers} onChanged={refreshSettings} onPick={() => setDialog("+")} onConfigure={(m) => setDialog(m)} />
{dialogEl}
</div>
@@ -237,6 +261,63 @@ 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. */
+function CustomProviderForm({
+ onCancel,
+ onCreated,
+}: {
+ onCancel: () => void;
+ onCreated: (name: string) => Promise<void>;
+}) {
+ const [title, setTitle] = useState("");
+ const [name, setName] = useState("");
+ 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 save = async () => {
+ setSaving(true);
+ setError(null);
+ const result: { ok: boolean; error?: string; provider?: string } = await createCustomProvider(
+ name,
+ title,
+ { base_url: baseUrl, api_key: apiKey },
+ ).catch(() => ({ ok: false, error: "unreachable" }));
+ setSaving(false);
+ if (!result.ok || !result.provider) {
+ setError(result.error || "Couldn’t add provider.");
+ 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>
+ </div>
+ );
+}
+
// The gallery view's "In the composer's picker" card: every curated model across providers,
// with its provider tag. Unticking removes it from the picker; adding happens from a
// provider's card (the ModelChecklist there has the suggested list + free-type add).
diff --git a/surfaces/gui/src/components/models/ProviderGroups.tsx b/surfaces/gui/src/components/models/ProviderGroups.tsx
index cba51e8b..5aa26bbd 100644
--- a/surfaces/gui/src/components/models/ProviderGroups.tsx
+++ b/surfaces/gui/src/components/models/ProviderGroups.tsx
@@ -39,10 +39,12 @@ export function ProviderGroups({
ps,
tp,
models,
+ onAddCustom,
}: {
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
}) {
const { t } = useTranslation();
const [query, setQuery] = useState("");
@@ -110,6 +112,19 @@ 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) && (
+ <button
+ className={card + " border-dashed bg-transparent text-muted hover:text-ink"}
+ data-testid={`${tp}-provider-custom-add`}
+ onClick={onAddCustom}
+ >
+ <span className="rounded-lg border border-line grid place-items-center shrink-0 text-[20px]" style={{ width: 32, height: 32 }}>
+ +
+ </span>
+ <span className="min-w-0 flex-1 text-ui font-semibold">{t("manage.custom_provider_card")}</span>
+ <span className="text-faint text-body">›</span>
+ </button>
+ )}
</div>
{!q && cards.length > FOLD && (
<button
diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.json
index c1fecfe0..0d82c75a 100644
--- a/surfaces/gui/src/locales/en.json
+++ b/surfaces/gui/src/locales/en.json
@@ -1347,6 +1347,9 @@
"remove_from_picker": "Remove from the picker",
"remove_key": "Remove key…",
"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",
"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 fa111121..04fee473 100644
--- a/surfaces/gui/src/locales/zh.json
+++ b/surfaces/gui/src/locales/zh.json
@@ -1330,6 +1330,9 @@
"remove_from_picker": "从选择器中移除",
"remove_key": "移除密钥…",
"remove_key_confirm": "从本机移除 {{title}} 密钥?",
+ "remove_provider": "移除提供商…",
+ "remove_provider_confirm": "从本机移除 {{title}} 提供商及其密钥?",
+ "custom_provider_card": "自定义提供商",
"signin_unlocks": "登录即可解锁 {{title}} 一键连接 —— 或在下方手动连接。",
"tool_asks_approval": "{{name}} · {{kind}} · 需审批",
"tools_exposed": "向 OpenWorker 提供的工具",
diff --git a/surfaces/gui/src/providers/ProviderSetup.tsx b/surfaces/gui/src/providers/ProviderSetup.tsx
index 1227b51f..e7992287 100644
--- a/surfaces/gui/src/providers/ProviderSetup.tsx
+++ b/surfaces/gui/src/providers/ProviderSetup.tsx
@@ -162,7 +162,9 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetup
setFields(next);
setDirty(!!draft && Object.values(draft).some(Boolean));
setVerify({ state: "idle" });
- setShowEndpoint(false);
+ // A custom provider cannot work without its endpoint, so keep that field
+ // visible instead of hiding it behind the built-ins' expert disclosure.
+ setShowEndpoint(!!p?.fields.find((f) => f.key === "base_url")?.required);
};
const backToGallery = () => {
@@ -180,14 +182,16 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetup
const runTestAndSave = async (): Promise<boolean> => {
if (!sel) return false;
setVerify({ state: "testing" });
- const res = await verifyProvider(sel, fields).catch(() => ({ ok: false, error: t("provider.err_unreachable") }));
+ const res: { ok: boolean; error?: string; warning?: string } = await verifyProvider(sel, fields).catch(
+ () => ({ ok: false, error: t("provider.err_unreachable") }),
+ );
if (!res.ok) {
setVerify({ state: "error", msg: res.error || t("provider.err_couldnt_verify") });
return false;
}
if (dirty || !info?.configured) await setProvider(sel, fields).catch(() => {});
if (!info?.needs_key) setKeylessOk((s) => new Set(s).add(sel));
- setVerify({ state: "ok" });
+ setVerify({ state: "ok", msg: res.warning });
setDirty(false);
setDrafts((d) => ({ ...d, [sel]: {} }));
await refreshProviders();
@@ -196,11 +200,15 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetup
// the timeout would fire its stale closure (dirty/fields from before the save) and
// re-stash the just-saved key as a draft — the state-restore bug (owner catch
// 2026-07-19). This return path clears the draft unconditionally.
- backTimer.current = window.setTimeout(() => {
- setDrafts((d) => ({ ...d, [sel]: {} }));
- setSel(null);
- setVerify({ state: "idle" });
- }, 900);
+ // A catalog-less gateway is still usable, but its warning contains the next action;
+ // leave the form open instead of making it disappear after the usual success animation.
+ if (!res.warning) {
+ backTimer.current = window.setTimeout(() => {
+ setDrafts((d) => ({ ...d, [sel]: {} }));
+ setSel(null);
+ setVerify({ state: "idle" });
+ }, 900);
+ }
return true;
};
@@ -413,11 +421,13 @@ export function ProviderCards({
tp,
gridClass = "grid grid-cols-2 gap-2.5",
lastUsed = false,
+ onAddCustom,
}: {
ps: ProviderSetupState;
tp: string; // testid prefix ("ob" onboarding, "set" settings)
gridClass?: string;
lastUsed?: boolean;
+ onAddCustom?: () => void;
}) {
const card =
"flex items-center gap-2.5 rounded-xl border border-line bg-panel px-3 py-2.5 text-left hover:border-lineStrong transition-colors";
@@ -438,6 +448,19 @@ export function ProviderCards({
<span className="text-faint text-body">›</span>
</button>
))}
+ {onAddCustom && (
+ <button
+ className={card + " border-dashed text-muted hover:text-ink"}
+ data-testid={`${tp}-provider-custom-add`}
+ onClick={onAddCustom}
+ >
+ <span className="rounded-lg border border-line grid place-items-center shrink-0 text-[20px]" style={{ width: 32, height: 32 }}>
+ +
+ </span>
+ <span className="min-w-0 flex-1 text-[13px] font-semibold">Custom provider</span>
+ <span className="text-faint text-[14px]">›</span>
+ </button>
+ )}
</div>
);
}
@@ -700,6 +723,7 @@ export function ProviderForm({
{/* Error line: fixed height so failures never reflow the form. */}
<div className="mt-3 min-h-[19px] text-ui">
{ps.verify.state === "error" && <span className="text-warnInk">{ps.verify.msg}</span>}
+ {ps.verify.state === "ok" && ps.verify.msg && <span className="text-muted">{ps.verify.msg}</span>}
</div>
{info?.auth === "oauth" ? null : footer}
</div>
diff --git a/tests/test_provider_router.py b/tests/test_provider_router.py
index ccf9bdd8..3781f449 100644
--- a/tests/test_provider_router.py
+++ b/tests/test_provider_router.py
@@ -5,6 +5,8 @@ from __future__ import annotations
from types import SimpleNamespace
+import pytest
+
from coworker.providers import (
AssistantTurn,
ModelCapabilities,
@@ -391,6 +393,110 @@ def test_manager_provider_config(tmp_path, monkeypatch):
assert mgr.set_provider("nope", {})["ok"] is False # unknown provider rejected
+def test_custom_openai_compatible_provider_routes_and_persists(tmp_path, monkeypatch):
+ """A custom route owns its key/endpoint and strips only its own prefix. The slug
+ must not be a built-in provider's name (openrouter is one now), so a neutral one."""
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ created = mgr.create_custom_provider(
+ "acme",
+ "Acme Gateway",
+ {"api_key": "acme-test", "base_url": "https://llm.acme.example/v1"},
+ )
+ assert created["ok"] is True and created["provider"] == "acme"
+
+ providers = {p["name"]: p for p in mgr.get_providers()}
+ assert providers["acme"]["is_custom"] is True
+ assert providers["acme"]["values"] == {
+ "base_url": "https://llm.acme.example/v1"
+ }
+ assert "acme-test" not in str(providers)
+
+ router = mgr.provider
+ assert router._provider_name("acme:anthropic/claude-example") == "acme"
+ assert (
+ router._bare("acme:anthropic/claude-example", mgr.secrets)
+ == "anthropic/claude-example"
+ )
+ client = router._client_for("acme:anthropic/claude-example")
+ assert client._api_key == "acme-test" and client._base_url == "https://llm.acme.example/v1"
+
+ mgr.add_model("acme:anthropic/claude-example")
+ assert "acme:anthropic/claude-example" in mgr.get_settings()["models"]
+ assert mgr.remove_provider("acme")["ok"] is True
+ assert "acme" not in {p["name"] for p in mgr.get_providers()}
+ assert "acme:anthropic/claude-example" not in mgr.get_settings()["models"]
+ # Existing sessions retain the full routed model id. After removal that must
+ # fail locally, never fall through to whichever provider is now the default.
+ assert router._provider_name("acme:anthropic/claude-example") == "acme"
+ with pytest.raises(RuntimeError, match="was removed"):
+ router.complete(model="acme:anthropic/claude-example", messages=[])
+
+ # Re-creating the same route intentionally clears its tombstone.
+ assert mgr.create_custom_provider(
+ "acme",
+ "Acme Gateway",
+ {"api_key": "acme-recreated", "base_url": "https://llm.acme.example/v1"},
+ )["ok"]
+ assert router._client_for("acme:anthropic/claude-example")._api_key == "acme-recreated"
+
+
+def test_custom_provider_requires_safe_route_and_complete_config(tmp_path, monkeypatch):
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ assert not mgr.create_custom_provider("Bad Name", "Gateway", {})["ok"]
+ assert not mgr.create_custom_provider(
+ "gateway", "Gateway", {"api_key": "x", "base_url": "gateway.example/v1"}
+ )["ok"]
+ assert not mgr.create_custom_provider(
+ "remote-http", "Remote HTTP", {"api_key": "x", "base_url": "http://example.com/v1"}
+ )["ok"]
+ assert mgr.create_custom_provider(
+ "local-http", "Local HTTP", {"api_key": "x", "base_url": "http://127.0.0.1:8000/v1"}
+ )["ok"]
+
+
+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
+
+ mgr = SessionManager(data_dir=tmp_path)
+ assert mgr.create_custom_provider(
+ "gateway", "Gateway", {"api_key": "test", "base_url": "https://gateway.example/v1"}
+ )["ok"]
+
+ monkeypatch.setattr(
+ "httpx.get", lambda *args, **kwargs: SimpleNamespace(status_code=404)
+ )
+ checked = mgr.verify_provider("gateway", {})
+ assert checked["ok"] is True and "does not expose /models" in checked["warning"]
+
+
+def test_custom_provider_verify_applies_endpoint_transport_policy(tmp_path, monkeypatch):
+ 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(
+ "gateway", "Gateway", {"api_key": "test", "base_url": "https://gateway.example/v1"}
+ )["ok"]
+
+ # Verify accepts unsaved form fields, so it must independently reject an
+ # unsafe replacement URL before it makes any request with the key.
+ monkeypatch.setattr(
+ "httpx.get", lambda *args, **kwargs: pytest.fail("unsafe endpoint was requested")
+ )
+ checked = mgr.verify_provider(
+ "gateway", {"base_url": "http://example.com/v1", "api_key": "test"}
+ )
+ assert checked["ok"] is False
+ assert "localhost or a private IP" in checked["error"]
+
+
def test_manager_curated_models(tmp_path, monkeypatch):
"""No seed list: the picker is the curated matrix filtered to key-holding providers,
plus user-added custom ids. A fresh install shows only the (not-yet-usable) default.
diff --git a/tests/test_server.py b/tests/test_server.py
index 75b50807..1786ce8c 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -1125,6 +1125,32 @@ def test_provider_set_and_remove_roundtrip(tmp_path):
assert not client.delete("/v1/providers/nope").json()["ok"]
+def test_custom_provider_rest_create_and_delete(tmp_path, monkeypatch):
+ """The public Settings API creates a separately-routed custom provider."""
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+ manager = SessionManager(workspace=tmp_path, provider=ScriptedProvider([]))
+ client = TestClient(create_app(manager))
+
+ created = client.post(
+ "/v1/providers/custom",
+ json={
+ "name": "acme",
+ "title": "Acme Gateway",
+ "fields": {
+ "api_key": "acme-test",
+ "base_url": "https://llm.acme.example/v1",
+ },
+ },
+ ).json()
+ assert created == {"ok": True, "provider": "acme", "recommended_model": None}
+ provider = {p["name"]: p for p in client.get("/v1/providers").json()}["acme"]
+ assert provider["is_custom"] is True and provider["values"]["base_url"].endswith("/v1")
+ assert "acme-test" not in str(provider)
+
+ assert client.delete("/v1/providers/acme").json()["ok"] is True
+ assert "acme" not in {p["name"] for p in client.get("/v1/providers").json()}
+
+
def test_always_allow_grants_survive_restart(tmp_path):
""""Always allow" is session-scoped, and the session outlives the process — a restart
(fresh manager over the same store) must not re-ask for an approved command