Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

feat(provider): connect bots to any OpenAI-compatible endpoint (#342)

Robbyn Rahmandaru51d4a5b481a5
diff --git a/.changeset/custom-openai-provider.md b/.changeset/custom-openai-provider.md
new file mode 100644
index 000000000..ec2c4edba
--- /dev/null
+++ b/.changeset/custom-openai-provider.md
@@ -0,0 +1,5 @@
+---
+"akeru-bot": minor
+---
+
+Add a Custom API provider that runs bots on any OpenAI-compatible endpoint. When you add one, pick OpenRouter, Groq, Together AI, DeepSeek, Mistral, Fireworks, LM Studio, Ollama, vLLM, or Other; a preset fills in the base URL and name. Paste a key into the API key field, which stores it as a secret. The model list comes from `{baseUrl}/models`, and model names you add by hand are kept. Several instances can run side by side, such as a local server and a hosted gateway.
diff --git a/apps/mobile/src/components/ProviderIcon.tsx b/apps/mobile/src/components/ProviderIcon.tsx
index f3f9ea815..b3f530d9e 100644
--- a/apps/mobile/src/components/ProviderIcon.tsx
+++ b/apps/mobile/src/components/ProviderIcon.tsx
@@ -51,6 +51,26 @@ export function ProviderIcon(props: ProviderIconProps) {
);
}
+ if (props.provider === "customOpenai") {
+ return (
+ <Svg
+ width={size}
+ height={size}
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke={mono}
+ strokeWidth={2}
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ >
+ <Path d="M12 22v-5" />
+ <Path d="M15 8V2" />
+ <Path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z" />
+ <Path d="M9 8V2" />
+ </Svg>
+ );
+ }
+
if (props.provider === "opencode" || props.provider === "opencodeGo") {
return (
<Svg width={size} height={size} viewBox="0 0 32 40" fill="none">
diff --git a/apps/mobile/src/features/threads/thread-list-v2-presentation.ts b/apps/mobile/src/features/threads/thread-list-v2-presentation.ts
index cd167a582..0d404ceb9 100644
--- a/apps/mobile/src/features/threads/thread-list-v2-presentation.ts
+++ b/apps/mobile/src/features/threads/thread-list-v2-presentation.ts
@@ -18,6 +18,7 @@ const PROVIDER_BOT_NAMES = new Map(
kimi: "Kimi",
opencode: "OpenCode",
opencodeGo: "OpenCode",
+ customOpenai: "Custom API",
} as const),
);
diff --git a/apps/server/src/provider/AkeruMastraHarness.models.test.ts b/apps/server/src/provider/AkeruMastraHarness.models.test.ts
index 3bd93611c..4decb457f 100644
--- a/apps/server/src/provider/AkeruMastraHarness.models.test.ts
+++ b/apps/server/src/provider/AkeruMastraHarness.models.test.ts
@@ -280,6 +280,39 @@ describe("AkeruMastraHarness", () => {
expect(getCredential).not.toHaveBeenCalled();
});
+ it("routes a Custom API model through its configured base URL and key", () => {
+ const authStorage = new AuthStorage("/tmp/akeru-unused-custom-openai-auth.json");
+ expect(
+ resolveAkeruMastraModel(
+ "custom-openai/local-model",
+ authStorage,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ {
+ environment: {
+ CUSTOM_OPENAI_API_KEY: "custom-key",
+ CUSTOM_OPENAI_BASE_URL: "http://localhost:11434/v1",
+ },
+ instanceEnvironment: {},
+ useSavedCredential: true,
+ },
+ ),
+ ).toMatchObject({ modelId: "local-model", provider: "custom-openai.chat" });
+ expect(() =>
+ resolveAkeruMastraModel(
+ "custom-openai/local-model",
+ authStorage,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ { environment: {}, instanceEnvironment: {}, useSavedCredential: true },
+ ),
+ ).toThrow(/needs a base URL/);
+ });
+
it("routes Claude and Grok models through their subscription transports", () => {
const authStorage = new AuthStorage("/tmp/akeru-unused-legacy-observer-auth.json");
diff --git a/apps/server/src/provider/Drivers/CustomOpenaiDriver.test.ts b/apps/server/src/provider/Drivers/CustomOpenaiDriver.test.ts
new file mode 100644
index 000000000..66a6bbbbd
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CustomOpenaiDriver.test.ts
@@ -0,0 +1,386 @@
+import { NodeServices } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import { ProviderDriverKind, ProviderInstanceId } from "@akeru/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { FetchHttpClient } from "effect/unstable/http";
+
+import { ServerConfig } from "../../config.ts";
+import { BUILT_IN_DRIVERS } from "../builtInDrivers.ts";
+import { CustomOpenaiDriver } from "./CustomOpenaiDriver.ts";
+
+const DRIVER_KIND = ProviderDriverKind.make("customOpenai");
+
+const INSTANCE_ID = ProviderInstanceId.make("customOpenai");
+
+const API_KEY_ENV = "CUSTOM_OPENAI_API_KEY";
+
+const BASE_URL_ENV = "CUSTOM_OPENAI_BASE_URL";
+
+interface RecordedRequest {
+ readonly url: string;
+ readonly authorization: string | null;
+}
+
+/** A `/models` endpoint whose answers the test flips between phases. */
+const catalogEndpoint = (responses: ReadonlyArray<Response>, recorded: RecordedRequest[] = []) => {
+ let index = 0;
+
+ return ((
+ input: Parameters<typeof globalThis.fetch>[0],
+ init: Parameters<typeof globalThis.fetch>[1],
+ ) => {
+ const headers = new Headers(init?.headers ?? undefined);
+ recorded.push({ url: String(input), authorization: headers.get("authorization") });
+ const response = responses[Math.min(index, responses.length - 1)]!;
+ index += 1;
+
+ return Promise.resolve(response.clone());
+ }) as typeof globalThis.fetch;
+};
+
+const modelListResponse = (modelIds: ReadonlyArray<string>) =>
+ new Response(
+ JSON.stringify({ object: "list", data: modelIds.map((id) => ({ id, object: "model" })) }),
+ { status: 200, headers: { "content-type": "application/json" } },
+ );
+
+const failingResponse = () =>
+ new Response("upstream unavailable", { status: 503, headers: { "content-type": "text/plain" } });
+
+const rejectedResponse = () =>
+ new Response('{"error":"invalid api key"}', {
+ status: 401,
+ headers: { "content-type": "application/json" },
+ });
+
+const unreadableResponse = () =>
+ new Response("<html>not json</html>", { status: 200, headers: { "content-type": "text/html" } });
+
+const testLayer = (prefix: string, fetch: typeof globalThis.fetch) =>
+ Layer.mergeAll(
+ ServerConfig.layerTest(process.cwd(), { prefix }).pipe(Layer.provideMerge(NodeServices.layer)),
+ FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, fetch))),
+ );
+
+const createInstance = (input: {
+ readonly config: Parameters<typeof CustomOpenaiDriver.create>[0]["config"];
+ readonly environment?: Parameters<typeof CustomOpenaiDriver.create>[0]["environment"];
+}) =>
+ CustomOpenaiDriver.create({
+ instanceId: INSTANCE_ID,
+ displayName: undefined,
+ environment: input.environment ?? [],
+ enabled: true,
+ config: input.config,
+ });
+
+const withApiKey = (name: string, value: string) => ({ name, value, sensitive: true });
+
+describe("CustomOpenaiDriver", () => {
+ it.effect("registers an endpoint-driven provider with no bundled models", () => {
+ expect(BUILT_IN_DRIVERS.map((driver) => String(driver.driverKind))).toContain("customOpenai");
+
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: CustomOpenaiDriver.defaultConfig(),
+ });
+
+ const snapshot = yield* instance.snapshot.getSnapshot;
+
+ return { instance, snapshot };
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(testLayer("akeru-custom-openai-driver-test-", catalogEndpoint([]))),
+ Effect.tap(({ instance, snapshot }) =>
+ Effect.sync(() => {
+ expect(instance.adapter).toBeUndefined();
+ expect(instance.textGeneration).toBeUndefined();
+ expect(instance.mastraConnection?.useSavedCredential).toBe(true);
+ expect(snapshot).toMatchObject({
+ instanceId: "customOpenai",
+ driver: DRIVER_KIND,
+ displayName: "Custom API",
+ status: "warning",
+ auth: { status: "unauthenticated", type: "apiKey" },
+ models: [],
+ message: "Set a base URL in Settings.",
+ });
+ }),
+ ),
+ );
+ });
+
+ it.effect("lists the endpoint catalog alongside hand-added models", () => {
+ const recorded: RecordedRequest[] = [];
+
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: {
+ ...CustomOpenaiDriver.defaultConfig(),
+ baseUrl: "https://api.example.com/v1/",
+ customModels: ["local-only", "gpt-4o-mini", " "],
+ },
+ environment: [withApiKey(API_KEY_ENV, "sk-test")],
+ });
+
+ const snapshot = yield* instance.snapshot.refresh;
+
+ return { instance, snapshot };
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(
+ testLayer(
+ "akeru-custom-openai-catalog-test-",
+ catalogEndpoint([modelListResponse(["gpt-4o-mini", "llama-3.3"])], recorded),
+ ),
+ ),
+ Effect.tap(({ instance, snapshot }) =>
+ Effect.sync(() => {
+ expect(recorded[0]).toMatchObject({
+ url: "https://api.example.com/v1/models",
+ authorization: "Bearer sk-test",
+ });
+ expect(snapshot.status).toBe("ready");
+ expect(snapshot.auth.status).toBe("authenticated");
+ expect(snapshot.message).toBeUndefined();
+ expect(snapshot.models).toMatchObject([
+ { slug: "gpt-4o-mini", isCustom: false, isDefault: true },
+ { slug: "llama-3.3", isCustom: false },
+ { slug: "local-only", isCustom: true },
+ ]);
+ expect(instance.mastraConnection?.environment).toMatchObject({
+ [API_KEY_ENV]: "sk-test",
+ [BASE_URL_ENV]: "https://api.example.com/v1/",
+ });
+ }),
+ ),
+ );
+ });
+
+ it.effect("keeps the last good catalog when a probe fails", () => {
+ const recorded: RecordedRequest[] = [];
+
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: {
+ ...CustomOpenaiDriver.defaultConfig(),
+ baseUrl: "https://user:[email protected]/v1/gateway-token",
+ },
+ });
+
+ const good = yield* instance.snapshot.refresh;
+ const failed = yield* instance.snapshot.refresh;
+
+ return { good, failed };
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(
+ testLayer(
+ "akeru-custom-openai-retain-test-",
+ catalogEndpoint([modelListResponse(["alpha", "beta"]), failingResponse()], recorded),
+ ),
+ ),
+ Effect.tap(({ good, failed }) =>
+ Effect.sync(() => {
+ expect(good.models.map((model) => model.slug)).toEqual(["alpha", "beta"]);
+ expect(good.status).toBe("ready");
+ // The endpoint is now unreachable: the catalog survives, and the
+ // snapshot stops claiming to be authoritative.
+ expect(failed.models.map((model) => model.slug)).toEqual(["alpha", "beta"]);
+ expect(failed.status).toBe("warning");
+ // Only the origin is published; credentials and paths stay private.
+ expect(failed.message).toBe("Model list from https://api.example.com returned HTTP 503.");
+ }),
+ ),
+ );
+ });
+
+ it.effect("flags a refused model listing without blocking the instance", () => {
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: { ...CustomOpenaiDriver.defaultConfig(), baseUrl: "https://api.example.com/v1" },
+ environment: [withApiKey(API_KEY_ENV, "sk-wrong")],
+ });
+
+ const rejected = yield* instance.snapshot.refresh;
+ const recovered = yield* instance.snapshot.refresh;
+
+ return { rejected, recovered };
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(
+ testLayer(
+ "akeru-custom-openai-rejected-test-",
+ catalogEndpoint([rejectedResponse(), modelListResponse(["alpha"])]),
+ ),
+ ),
+ Effect.tap(({ rejected, recovered }) =>
+ Effect.sync(() => {
+ expect(rejected.status).toBe("warning");
+ expect(rejected.auth.status).toBe("unknown");
+ expect(rejected.message).toBe(
+ "https://api.example.com refused to list models (HTTP 401). Check the API key in Settings.",
+ );
+ expect(recovered.auth.status).toBe("authenticated");
+ expect(recovered.status).toBe("ready");
+ }),
+ ),
+ );
+ });
+
+ it.effect("never contacts the endpoint while the instance is disabled", () => {
+ const recorded: RecordedRequest[] = [];
+
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: {
+ ...CustomOpenaiDriver.defaultConfig(),
+ enabled: false,
+ baseUrl: "https://api.example.com/v1",
+ },
+ environment: [withApiKey(API_KEY_ENV, "sk-test")],
+ });
+
+ return yield* instance.snapshot.refresh;
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(
+ testLayer(
+ "akeru-custom-openai-disabled-test-",
+ catalogEndpoint([modelListResponse(["alpha"])], recorded),
+ ),
+ ),
+ Effect.tap((snapshot) =>
+ Effect.sync(() => {
+ expect(snapshot.status).toBe("disabled");
+ expect(recorded).toEqual([]);
+ }),
+ ),
+ );
+ });
+
+ it.effect("treats an unreadable model list as a failed probe", () => {
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: {
+ ...CustomOpenaiDriver.defaultConfig(),
+ baseUrl: "http://localhost:11434/v1",
+ customModels: ["llama3.2"],
+ },
+ });
+
+ return yield* instance.snapshot.refresh;
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(
+ testLayer("akeru-custom-openai-unreadable-test-", catalogEndpoint([unreadableResponse()])),
+ ),
+ Effect.tap((snapshot) =>
+ Effect.sync(() => {
+ expect(snapshot.status).toBe("warning");
+ expect(snapshot.message).toBe(
+ "Model list from http://localhost:11434 was not a readable list of models.",
+ );
+ // A keyless local endpoint still runs turns; only the catalog is unknown.
+ expect(snapshot.auth).toMatchObject({ status: "authenticated", type: "apiKey" });
+ expect(snapshot.models).toMatchObject([{ slug: "llama3.2", isCustom: true }]);
+ }),
+ ),
+ );
+ });
+
+ it.effect("ignores process-level endpoint variables", () => {
+ const previousKey = process.env[API_KEY_ENV];
+ const previousUrl = process.env[BASE_URL_ENV];
+ process.env[API_KEY_ENV] = "process-wide-key";
+ process.env[BASE_URL_ENV] = "https://process.invalid/v1";
+
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: CustomOpenaiDriver.defaultConfig(),
+ });
+
+ return { instance, snapshot: yield* instance.snapshot.getSnapshot };
+ }),
+ );
+
+ return program.pipe(
+ Effect.ensuring(
+ Effect.sync(() => {
+ if (previousKey === undefined) delete process.env[API_KEY_ENV];
+ else process.env[API_KEY_ENV] = previousKey;
+
+ if (previousUrl === undefined) delete process.env[BASE_URL_ENV];
+ else process.env[BASE_URL_ENV] = previousUrl;
+ }),
+ ),
+ Effect.provide(testLayer("akeru-custom-openai-ambient-test-", catalogEndpoint([]))),
+ Effect.tap(({ instance, snapshot }) =>
+ Effect.sync(() => {
+ // An instance that configures neither would otherwise send the
+ // process key to the process endpoint.
+ expect(instance.mastraConnection?.environment).not.toHaveProperty(API_KEY_ENV);
+ expect(instance.mastraConnection?.environment).not.toHaveProperty(BASE_URL_ENV);
+ expect(snapshot.status).toBe("warning");
+ expect(snapshot.message).toBe("Set a base URL in Settings.");
+ }),
+ ),
+ );
+ });
+
+ it.effect("prefers instance environment variables over the settings blob", () => {
+ const program = Effect.scoped(
+ Effect.gen(function* () {
+ const instance = yield* createInstance({
+ config: {
+ ...CustomOpenaiDriver.defaultConfig(),
+ baseUrl: "https://config.invalid/v1",
+ },
+ environment: [
+ { name: BASE_URL_ENV, value: "http://localhost:11434/v1", sensitive: false },
+ withApiKey(API_KEY_ENV, "env-key"),
+ ],
+ });
+
+ return { instance, snapshot: yield* instance.snapshot.getSnapshot };
+ }),
+ );
+
+ return program.pipe(
+ Effect.provide(testLayer("akeru-custom-openai-env-test-", catalogEndpoint([]))),
+ Effect.tap(({ instance, snapshot }) =>
+ Effect.sync(() => {
+ expect(snapshot.auth.status).toBe("authenticated");
+ expect(instance.mastraConnection?.environment).toMatchObject({
+ [API_KEY_ENV]: "env-key",
+ [BASE_URL_ENV]: "http://localhost:11434/v1",
+ });
+ expect(instance.mastraConnection?.instanceEnvironment).toMatchObject({
+ [API_KEY_ENV]: "env-key",
+ [BASE_URL_ENV]: "http://localhost:11434/v1",
+ });
+ }),
+ ),
+ );
+ });
+});
diff --git a/apps/server/src/provider/Drivers/CustomOpenaiDriver.ts b/apps/server/src/provider/Drivers/CustomOpenaiDriver.ts
new file mode 100644
index 000000000..4712f0800
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CustomOpenaiDriver.ts
@@ -0,0 +1,332 @@
+import {
+ CustomOpenaiSettings,
+ ProviderDriverKind,
+ type ServerProvider,
+ type ServerProviderModel,
+} from "@akeru/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+
+import { ServerConfig } from "../../config.ts";
+import { mergeSubscriptionInstanceEnvironment } from "../../subscription-auth/runtime.ts";
+import { defaultProviderContinuationIdentity, type ProviderDriver } from "../ProviderDriver.ts";
+import { explicitProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import { manualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+
+const DRIVER_KIND = ProviderDriverKind.make("customOpenai");
+
+const decodeSettings = Schema.decodeSync(CustomOpenaiSettings);
+
+/**
+ * The API key is an instance environment variable, not a config field: the
+ * settings blob is serialized to every client that can read settings, and only
+ * sensitive environment variables are stored in the secret store and redacted
+ * on the way out. Instance variables win over the process environment, which is
+ * deliberately NOT read here — this driver talks to an arbitrary endpoint, so
+ * inheriting a process-wide key would send it to whatever URL an instance
+ * happens to configure.
+ */
+const API_KEY_ENV = "CUSTOM_OPENAI_API_KEY";
+
+const BASE_URL_ENV = "CUSTOM_OPENAI_BASE_URL";
+
+/** The whole `/models` probe — request, headers, and body — must fit this budget. */
+const MODELS_TIMEOUT_MS = 10_000;
+
+/**
+ * OpenAI-compatible `/models` payloads come in two shapes: the standard
+ * `{ data: [{ id }] }` envelope and a bare array from smaller gateways.
+ * The envelope is validated as a whole so an unreadable body is reported as a
+ * failed probe rather than as an endpoint that lists no models; entries are
+ * decoded one at a time so a single malformed row cannot discard the catalog.
+ *
+ * `None` means "not a model list at all".
+ */
+const EndpointModelEnvelope = Schema.Struct({ data: Schema.Array(Schema.Unknown) });
+
+const EndpointModelArray = Schema.Array(Schema.Unknown);
+
+const EndpointModelList = Schema.Union([EndpointModelEnvelope, EndpointModelArray]);
+
+const EndpointModelEntry = Schema.Union([Schema.String, Schema.Struct({ id: Schema.String })]);
+
+const decodeEndpointModelList = Schema.decodeUnknownOption(EndpointModelList);
+
+const decodeEndpointModelEntry = Schema.decodeUnknownOption(EndpointModelEntry);
+
+function readEndpointModelIds(
+ list: typeof EndpointModelList.Type,
+): Option.Option<ReadonlyArray<string>> {
+ const entries = "data" in list ? list.data : list;
+ const ids = new Set<string>();
+
+ for (const entry of entries) {
+ const resolved = decodeEndpointModelEntry(entry).pipe(
+ Option.map((model) => (Predicate.isString(model) ? model : model.id).trim()),
+ Option.filter((value) => value.length > 0),
+ );
+
+ if (Option.isSome(resolved)) ids.add(resolved.value);
+ }
+
+ return Option.some([...ids]);
+}
+
+/**
+ * The instance's catalog is whatever the endpoint reports plus every model the
+ * user added by hand. Endpoint models are the provider's own list; hand-added
+ * ones stay flagged custom so settings can tell them apart.
+ */
+function models(
+ catalog: readonly string[],
+ customModels: readonly string[],
+): ServerProviderModel[] {
+ const custom = customModels.flatMap((model) => {
+ const trimmed = model.trim();
+
+ return trimmed.length > 0 ? [trimmed] : [];
+ });
+
+ const catalogSlugs = new Set(catalog);
+
+ return [...new Set([...catalog, ...custom])].map((slug, index) => ({
+ slug,
+ name: slug,
+ isCustom: !catalogSlugs.has(slug),
+ ...(index === 0 ? { isDefault: true } : {}),
+ capabilities: null,
+ }));
+}
+
+type ProbeResult =
+ | { readonly ok: true; readonly catalog: ReadonlyArray<string> }
+ | { readonly ok: false; readonly failure: string; readonly rejected: boolean };
+
+export type CustomOpenaiDriverEnv = ServerConfig | HttpClient.HttpClient;
+
+export const CustomOpenaiDriver: ProviderDriver<CustomOpenaiSettings, CustomOpenaiDriverEnv> = {
+ driverKind: DRIVER_KIND,
+ metadata: { displayName: "Custom API", supportsMultipleInstances: true },
+ configSchema: CustomOpenaiSettings,
+ defaultConfig: () => decodeSettings({}),
+ create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+ Effect.gen(function* () {
+ const httpClient = yield* HttpClient.HttpClient;
+
+ const changes = yield* Effect.acquireRelease(
+ PubSub.unbounded<ServerProvider>(),
+ PubSub.shutdown,
+ );
+
+ const catalog = yield* Ref.make<ReadonlyArray<string>>([]);
+ const probeFailure = yield* Ref.make<string | null>(null);
+ // True after `/models` answered 401 or 403. A scoped key can be refused
+ // the listing and still chat, so this only stops the instance reading
+ // as connected; it does not block turns.
+ const probeRejected = yield* Ref.make(false);
+ // False until the first probe settles. The catalog is not authoritative
+ // before then, so the registry keeps the models it hydrated from the
+ // on-disk cache instead of trusting an empty list.
+ const probeSettled = yield* Ref.make(false);
+ // One probe at a time: an explicit refresh must not race the startup
+ // probe and let the older response land last.
+ const probeLock = yield* Semaphore.make(1);
+ const effectiveEnabled = enabled && config.enabled;
+ const explicitEnvironment = explicitProviderInstanceEnvironment(environment);
+ const apiKey = explicitEnvironment[API_KEY_ENV]?.trim() ?? "";
+ const baseUrl = explicitEnvironment[BASE_URL_ENV]?.trim() || config.baseUrl.trim();
+
+ const connectionEnvironment: NodeJS.ProcessEnv = {
+ ...mergeSubscriptionInstanceEnvironment(environment),
+ ...(apiKey.length > 0 ? { [API_KEY_ENV]: apiKey } : {}),
+ ...(baseUrl.length > 0 ? { [BASE_URL_ENV]: baseUrl } : {}),
+ };
+
+ // Drop anything the process environment supplied for these two names:
+ // only the instance's own variables and its configured base URL count.
+ if (apiKey.length === 0) delete connectionEnvironment[API_KEY_ENV];
+
+ if (baseUrl.length === 0) delete connectionEnvironment[BASE_URL_ENV];
+ // A base URL alone is enough to run turns: plenty of OpenAI-compatible
+ // servers (Ollama, llama.cpp, LM Studio) take no API key. `auth.status`
+ // is the app-wide "this instance can run" signal, so it follows the base
+ // URL rather than the key; the key is only sent when one is configured.
+ // A `/models` refusal (401/403) downgrades it to "unknown", which shows
+ // the warning without gating turns the way "unauthenticated" does.
+ const connected = baseUrl.length > 0;
+
+ // Probe failures are published to every client. The base URL may come
+ // from a sensitive variable, so messages name only its origin.
+ const endpointLabel = URL.canParse(baseUrl) ? new URL(baseUrl).origin : "the endpoint";
+
+ const continuationIdentity = defaultProviderContinuationIdentity({
+ driverKind: DRIVER_KIND,
+ instanceId,
+ });
+
+ const buildSnapshot = Effect.gen(function* () {
+ const endpointModels = yield* Ref.get(catalog);
+ const failure = yield* Ref.get(probeFailure);
+ const settled = yield* Ref.get(probeSettled);
+ const rejected = yield* Ref.get(probeRejected);
+
+ const message = !connected
+ ? "Set a base URL in Settings."
+ : (failure ?? (settled ? undefined : "Listing models from the endpoint…"));
+
+ // `warning` covers every state whose catalog is not authoritative:
+ // disabled, no base URL, an in-flight first probe, and a failed probe
+ // that is still serving the last good catalog.
+ return {
+ instanceId,
+ driver: DRIVER_KIND,
+ displayName: displayName ?? "Custom API",
+ ...(accentColor ? { accentColor } : {}),
+ continuation: { groupKey: continuationIdentity.continuationKey },
+ enabled: effectiveEnabled,
+ installed: true,
+ version: null,
+ status: !effectiveEnabled
+ ? "disabled"
+ : connected && failure === null && settled
+ ? "ready"
+ : "warning",
+ auth: {
+ status: !connected ? "unauthenticated" : rejected ? "unknown" : "authenticated",
+ type: "apiKey",
+ },
+ checkedAt: DateTime.formatIso(DateTime.nowUnsafe()),
+ ...(effectiveEnabled && message !== undefined ? { message } : {}),
+ availability: "available",
+ models: models(endpointModels, config.customModels),
+ slashCommands: [],
+ skills: [],
+ } satisfies ServerProvider;
+ });
+
+ const probeEndpointModels: Effect.Effect<ProbeResult> = Effect.gen(function* () {
+ const bare = HttpClientRequest.get(`${baseUrl.replace(/\/+$/, "")}/models`).pipe(
+ HttpClientRequest.setHeader("accept", "application/json"),
+ );
+
+ const request = apiKey.length > 0 ? HttpClientRequest.bearerToken(apiKey)(bare) : bare;
+
+ // One timeout covers the request, the response headers, and the body:
+ // a gateway that answers 200 and then stalls must not hang a refresh.
+ const outcome = yield* Effect.gen(function* () {
+ const response = yield* httpClient.execute(request);
+
+ if (response.status === 401 || response.status === 403) {
+ return {
+ ok: false as const,
+ failure: `${endpointLabel} refused to list models (HTTP ${response.status}). Check the API key in Settings.`,
+ rejected: true,
+ } satisfies ProbeResult;
+ }
+
+ if (response.status < 200 || response.status >= 300) {
+ return {
+ ok: false as const,
+ failure: `Model list from ${endpointLabel} returned HTTP ${response.status}.`,
+ rejected: false,
+ } satisfies ProbeResult;
+ }
+
+ const ids = yield* response.json.pipe(
+ Effect.map((body) =>
+ Option.flatMap(decodeEndpointModelList(body), readEndpointModelIds),
+ ),
+ // A body that is not JSON at all is as unreadable as one with the
+ // wrong shape; both mean "this is not a model list".
+ Effect.orElseSucceed(() => Option.none()),
+ );
+
+ return Option.isSome(ids)
+ ? { ok: true as const, catalog: ids.value }
+ : {
+ ok: false as const,
+ failure: `Model list from ${endpointLabel} was not a readable list of models.`,
+ rejected: false,
+ };
+ }).pipe(
+ Effect.timeoutOption(MODELS_TIMEOUT_MS),
+ Effect.catchCause(() => Effect.succeed(Option.none())),
+ );
+
+ return Option.isNone(outcome)
+ ? { ok: false, failure: `Could not list models from ${endpointLabel}.`, rejected: false }
+ : outcome.value;
+ });
+
+ const refresh = probeLock.withPermits(1)(
+ Effect.gen(function* () {
+ // Disabled instances publish their snapshot without contacting the
+ // endpoint, so a configured key is never sent.
+ if (!connected || !effectiveEnabled) {
+ yield* Ref.set(probeFailure, null);
+ yield* Ref.set(probeRejected, false);
+ yield* Ref.set(probeSettled, false);
+ } else {
+ const result = yield* probeEndpointModels;
+
+ if (result.ok) {
+ yield* Ref.set(catalog, result.catalog);
+ yield* Ref.set(probeFailure, null);
+ yield* Ref.set(probeRejected, false);
+ } else {
+ // Keep the last good catalog: a transient failure must not empty
+ // the picker or block models the endpoint still serves.
+ yield* Ref.set(probeFailure, result.failure);
+ yield* Ref.set(probeRejected, result.rejected);
+ }
+
+ yield* Ref.set(probeSettled, true);
+ }
+
+ const snapshot = yield* buildSnapshot;
+ yield* PubSub.publish(changes, snapshot);
+
+ return snapshot;
+ }),
+ );
+
+ // Populate the catalog without blocking the registry's layer build.
+ yield* Effect.forkScoped(refresh);
+
+ return {
+ instanceId,
+ driverKind: DRIVER_KIND,
+ continuationIdentity,
+ displayName,
+ accentColor,
+ enabled: effectiveEnabled,
+ mastraConnection: {
+ environment: connectionEnvironment,
+ instanceEnvironment: explicitEnvironment,
+ // No subscription credential exists for this driver; `true` selects
+ // the merged `environment` (which carries the instance key and base
+ // URL) in `resolveAkeruMastraModel`.
+ useSavedCredential: true,
+ },
+ adapter: undefined,
+ textGeneration: undefined,
+ snapshot: {
+ maintenanceCapabilities: manualOnlyProviderMaintenanceCapabilities({
+ provider: DRIVER_KIND,
+ packageName: null,
+ }),
+ getSnapshot: buildSnapshot,
+ refresh,
+ streamChanges: Stream.fromPubSub(changes),
+ },
+ };
+ }),
+};
diff --git a/apps/server/src/provider/Layers/AgentController.test.ts b/apps/server/src/provider/Layers/AgentController.test.ts
index 4bd8b06bd..647da5155 100644
--- a/apps/server/src/provider/Layers/AgentController.test.ts
+++ b/apps/server/src/provider/Layers/AgentController.test.ts
@@ -126,6 +126,31 @@ describe("mastraConnectionIssue", () => {
),
);
});
+
+ it("gates a Custom API instance on its configured base URL alone", () => {
+ const customOpenai = ProviderDriverKind.make("customOpenai");
+ assert.isUndefined(
+ mastraConnectionIssue(
+ customOpenai,
+ {
+ environment: { CUSTOM_OPENAI_BASE_URL: "http://localhost:11434/v1" },
+ instanceEnvironment: {},
+ useSavedCredential: true,
+ },
+ false,
+ ),
+ );
+ // A saved subscription credential is not a substitute for the endpoint:
+ // the branch must win over the generic saved-credential path.
+ assert.equal(
+ mastraConnectionIssue(
+ customOpenai,
+ { environment: {}, instanceEnvironment: {}, useSavedCredential: true },
+ true,
+ ),
+ "This Custom API instance needs a base URL.",
+ );
+ });
});
describe("toMcpServerConfigs", () => {
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.refresh.recovery.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.refresh.recovery.test.ts
index 4318433be..cb6b5eabc 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.refresh.recovery.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.refresh.recovery.test.ts
@@ -349,6 +349,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
assert.deepStrictEqual(providers.map((provider) => provider.instanceId).toSorted(), [
"claudeAgent",
"codex",
+ "customOpenai",
"grok",
"kimi",
"opencodeGo",
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index 9656708bf..fb45282ce 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -329,6 +329,120 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
"ProviderRegistry",
(it) => {
describe("ProviderRegistryLive", () => {
+ it("drops Custom API models only once a catalog probe settles", () => {
+ const model = (slug: string) => ({
+ slug,
+ name: slug,
+ isCustom: false,
+ capabilities: null,
+ });
+
+ const previousProvider = {
+ instanceId: ProviderInstanceId.make("customOpenai"),
+ driver: ProviderDriverKind.make("customOpenai"),
+ status: "ready",
+ enabled: true,
+ installed: true,
+ auth: { status: "authenticated" },
+ checkedAt: "2026-07-17T00:00:00.000Z",
+ version: null,
+ // The user removed "hand-added" in Settings; no probe state may revive it.
+ models: [
+ model("alpha"),
+ model("removed-by-endpoint"),
+ { ...model("hand-added"), isCustom: true },
+ ],
+ slashCommands: [],
+ skills: [],
+ } as const satisfies ServerProvider;
+
+ const settledProbe = {
+ ...previousProvider,
+ checkedAt: "2026-07-17T00:01:00.000Z",
+ models: [model("alpha")],
+ } satisfies ServerProvider;
+
+ const failedProbe = {
+ ...settledProbe,
+ status: "warning",
+ message: "Could not list models from https://api.example.com.",
+ } satisfies ServerProvider;
+
+ const pendingFirstProbe = {
+ ...settledProbe,
+ status: "warning",
+ message: "Listing models from the endpoint…",
+ } satisfies ServerProvider;
+
+ assert.deepStrictEqual(
+ mergeProviderSnapshot(previousProvider, settledProbe).models.map((entry) => entry.slug),
+ ["alpha"],
+ );
+ assert.deepStrictEqual(
+ mergeProviderSnapshot(previousProvider, failedProbe).models.map((entry) => entry.slug),
+ ["alpha", "removed-by-endpoint"],
+ );
+ assert.deepStrictEqual(
+ mergeProviderSnapshot(previousProvider, pendingFirstProbe).models.map(
+ (entry) => entry.slug,
+ ),
+ ["alpha", "removed-by-endpoint"],
+ );
+ assert.deepStrictEqual(
+ mergeProviderSnapshot(previousProvider, { ...failedProbe, models: [] }).models.map(
+ (entry) => entry.slug,
+ ),
+ ["alpha", "removed-by-endpoint"],
+ );
+ });
+
+ it("keeps an endpoint model through a pending probe when it was also hand-added", () => {
+ const model = (slug: string, isCustom: boolean) => ({
+ slug,
+ name: slug,
+ isCustom,
+ capabilities: null,
+ });
+
+ const discovered = {
+ instanceId: ProviderInstanceId.make("customOpenai"),
+ driver: ProviderDriverKind.make("customOpenai"),
+ status: "ready",
+ enabled: true,
+ installed: true,
+ auth: { status: "authenticated" },
+ checkedAt: "2026-07-17T00:00:00.000Z",
+ version: null,
+ models: [model("alpha", false)],
+ slashCommands: [],
+ skills: [],
+ } as const satisfies ServerProvider;
+
+ // After a restart the driver has no catalog yet, so the hand-added
+ // "alpha" arrives marked custom.
+ const pendingWithHandAdded = {
+ ...discovered,
+ status: "warning",
+ message: "Listing models from the endpoint…",
+ models: [model("alpha", true)],
+ } satisfies ServerProvider;
+
+ const pending = mergeProviderSnapshot(discovered, pendingWithHandAdded);
+ assert.deepStrictEqual(pending.models, [model("alpha", false)]);
+
+ // The user then removes the hand-added copy while the probe still fails.
+ const failedWithoutHandAdded = {
+ ...pendingWithHandAdded,
+ message: "Could not list models from https://api.example.com.",
+ models: [],
+ } satisfies ServerProvider;
+
+ assert.deepStrictEqual(
+ mergeProviderSnapshot(pending, failedWithoutHandAdded).models.map((entry) => entry.slug),
+ ["alpha"],
+ );
+ });
+
it("classifies pending, logout, uninstall, and reconnect OpenCode inventories", () => {
const previousProvider = {
instanceId: ProviderInstanceId.make("opencode"),
diff --git a/apps/server/src/provider/Layers/agentController/ProviderAccess.ts b/apps/server/src/provider/Layers/agentController/ProviderAccess.ts
index a21e01ab4..2a2bf820a 100644
--- a/apps/server/src/provider/Layers/agentController/ProviderAccess.ts
+++ b/apps/server/src/provider/Layers/agentController/ProviderAccess.ts
@@ -92,6 +92,14 @@ export function mastraConnectionIssue(
? connection.environment
: connection.instanceEnvironment;
+ // A custom endpoint has no subscription account to connect: the base URL is
+ // the whole credential story, so neither branch below applies.
+ if (String(provider) === "customOpenai") {
+ return env.CUSTOM_OPENAI_BASE_URL?.trim()
+ ? undefined
+ : "This Custom API instance needs a base URL.";
+ }
+
if (connection.useSavedCredential) {
const hasAmbientCredential = (() => {
switch (String(provider)) {
diff --git a/apps/server/src/provider/Layers/registry/ProviderSnapshotMerge.ts b/apps/server/src/provider/Layers/registry/ProviderSnapshotMerge.ts
index d82c6f5ea..498915a68 100644
--- a/apps/server/src/provider/Layers/registry/ProviderSnapshotMerge.ts
+++ b/apps/server/src/provider/Layers/registry/ProviderSnapshotMerge.ts
@@ -13,6 +13,15 @@ export const shouldRetainMissingProviderModels = (provider: ServerProvider): boo
return provider.enabled && provider.status !== "ready";
}
+ if (provider.driver === ProviderDriverKind.make("customOpenai")) {
+ // A Custom API endpoint is the whole inventory: once a `/models` probe
+ // settles, a model it no longer reports is genuinely gone. While the first
+ // probe is still in flight, the instance has no base URL, or the last probe
+ // failed, the snapshot is not authoritative and keeps the last good list
+ // (including the models hydrated from the on-disk cache at boot).
+ return provider.enabled && provider.status !== "ready";
+ }
+
if (provider.driver !== ProviderDriverKind.make("opencode")) {
return true;
}
@@ -38,14 +47,32 @@ export const mergeProviderModels = (
): ReadonlyArray<ServerProvider["models"][number]> => {
const shouldRetainMissingModels = shouldRetainMissingProviderModels(provider);
- if (shouldRetainMissingModels && nextModels.length === 0 && previousModels.length > 0) {
- return previousModels;
+ // Custom API models added by hand come from settings, not discovery, so the
+ // driver always reports the current list. A removed one must not be kept.
+ const retainableModels =
+ provider.driver === ProviderDriverKind.make("customOpenai")
+ ? previousModels.filter((model) => !model.isCustom)
+ : previousModels;
+
+ if (shouldRetainMissingModels && nextModels.length === 0 && retainableModels.length > 0) {
+ return retainableModels;
}
const previousBySlug = new Map(previousModels.map((model) => [model.slug, model] as const));
- const mergedModels = nextModels.map((model) => {
- const previousModel = previousBySlug.get(model.slug);
+ // Before a Custom API probe settles, the driver marks every hand-added model
+ // custom, even one the last good catalog also listed. Keep the endpoint's
+ // claim so removing the hand-added copy does not drop the model.
+ const keepsDiscoveredModels =
+ shouldRetainMissingModels && provider.driver === ProviderDriverKind.make("customOpenai");
+
+ const mergedModels = nextModels.map((nextModel) => {
+ const previousModel = previousBySlug.get(nextModel.slug);
+
+ const model =
+ keepsDiscoveredModels && nextModel.isCustom && previousModel?.isCustom === false
+ ? { ...nextModel, isCustom: false }
+ : nextModel;
if (!previousModel || hasModelCapabilities(model) || !hasModelCapabilities(previousModel)) {
return model;
@@ -60,7 +87,7 @@ export const mergeProviderModels = (
const nextSlugs = new Set(nextModels.map((model) => model.slug));
return shouldRetainMissingModels
- ? [...mergedModels, ...previousModels.filter((model) => !nextSlugs.has(model.slug))]
+ ? [...mergedModels, ...retainableModels.filter((model) => !nextSlugs.has(model.slug))]
: mergedModels;
};
diff --git a/apps/server/src/provider/builtInDrivers.ts b/apps/server/src/provider/builtInDrivers.ts
index e196de927..20a158986 100644
--- a/apps/server/src/provider/builtInDrivers.ts
+++ b/apps/server/src/provider/builtInDrivers.ts
@@ -22,6 +22,7 @@
*/
import { ClaudeDriver, type ClaudeDriverEnv } from "./Drivers/ClaudeDriver.ts";
import { CodexDriver, type CodexDriverEnv } from "./Drivers/CodexDriver.ts";
+import { CustomOpenaiDriver, type CustomOpenaiDriverEnv } from "./Drivers/CustomOpenaiDriver.ts";
import { GrokDriver, type GrokDriverEnv } from "./Drivers/GrokDriver.ts";
import { KimiDriver, type KimiDriverEnv } from "./Drivers/KimiDriver.ts";
import { OpenCodeDriver, type OpenCodeDriverEnv } from "./Drivers/OpenCodeDriver.ts";
@@ -40,7 +41,8 @@ export type BuiltInDriversEnv =
| GrokDriverEnv
| KimiDriverEnv
| OpenCodeDriverEnv
- | OpenCodeGoDriverEnv;
+ | OpenCodeGoDriverEnv
+ | CustomOpenaiDriverEnv;
/**
* Ordered list of built-in drivers. Order matters only for tie-breaking in
@@ -54,4 +56,5 @@ export const BUILT_IN_DRIVERS: ReadonlyArray<AnyProviderDriver<BuiltInDriversEnv
registeredProviderDriver(KimiDriver),
registeredProviderDriver(OpenCodeDriver),
registeredProviderDriver(OpenCodeGoDriver),
+ registeredProviderDriver(CustomOpenaiDriver),
];
diff --git a/apps/server/src/provider/mastra/AkeruModels.ts b/apps/server/src/provider/mastra/AkeruModels.ts
index 35795c351..9df9d7389 100644
--- a/apps/server/src/provider/mastra/AkeruModels.ts
+++ b/apps/server/src/provider/mastra/AkeruModels.ts
@@ -62,6 +62,7 @@ export const MASTRA_MODEL_PREFIX = {
grok: "xai",
kimi: "kimi-for-coding",
opencodeGo: "opencode-go",
+ customOpenai: "custom-openai",
} as const;
export function mastraModelId(provider: ProviderDriverKind, model: string): string {
@@ -288,5 +289,18 @@ export function resolveAkeruMastraModel(
);
}
+ if (trimmed.startsWith("custom-openai/")) {
+ const apiKey = environment?.CUSTOM_OPENAI_API_KEY?.trim();
+ const baseUrl = environment?.CUSTOM_OPENAI_BASE_URL?.trim();
+
+ if (!baseUrl) throw new Error("This Custom API instance needs a base URL.");
+
+ return createOpenAICompatible({
+ name: "custom-openai",
+ ...(apiKey ? { apiKey } : {}),
+ baseURL: baseUrl,
+ })(trimmed.slice("custom-openai/".length));
+ }
+
throw new Error(`Mastra has no subscription transport for model '${modelId}'.`);
}
diff --git a/apps/server/src/serverSettingsProviders.ts b/apps/server/src/serverSettingsProviders.ts
index ae74e4b77..fc10641a5 100644
--- a/apps/server/src/serverSettingsProviders.ts
+++ b/apps/server/src/serverSettingsProviders.ts
@@ -143,7 +143,11 @@ export function restoreUsedProviders(
export const RETIRED_PROVIDER_DRIVERS: ReadonlySet<string> = new Set(["cursor"]);
// Live drivers whose instances expose no text generation.
-export const NO_TEXT_GENERATION_DRIVERS: ReadonlySet<string> = new Set(["kimi", "opencodeGo"]);
+export const NO_TEXT_GENERATION_DRIVERS: ReadonlySet<string> = new Set([
+ "kimi",
+ "opencodeGo",
+ "customOpenai",
+]);
export function isRetiredProviderInstance(settings: ServerSettings, instanceId: string): boolean {
const driver = settings.providerInstances[ProviderInstanceId.make(instanceId)]?.driver;
diff --git a/apps/web/src/components/Icons.tsx b/apps/web/src/components/Icons.tsx
index c0e5725e9..239a991d5 100644
--- a/apps/web/src/components/Icons.tsx
+++ b/apps/web/src/components/Icons.tsx
@@ -2,7 +2,14 @@ export { VisualStudioCode, VisualStudioCodeInsiders, VSCodium, Zed } from "./ico
export { type Icon } from "./icons/iconTypes";
-export { ClaudeAI, GrokIcon, KimiIcon, OpenAI, OpenCodeIcon } from "./icons/ProviderIcons";
+export {
+ ClaudeAI,
+ CustomApiIcon,
+ GrokIcon,
+ KimiIcon,
+ OpenAI,
+ OpenCodeIcon,
+} from "./icons/ProviderIcons";
export {
ACPRegistryIcon,
diff --git a/apps/web/src/components/chat/providerIconUtils.ts b/apps/web/src/components/chat/providerIconUtils.ts
index 15f2408cd..573658c27 100644
--- a/apps/web/src/components/chat/providerIconUtils.ts
+++ b/apps/web/src/components/chat/providerIconUtils.ts
@@ -1,5 +1,5 @@
import { ProviderDriverKind } from "@akeru/contracts";
-import { ClaudeAI, GrokIcon, Icon, KimiIcon, OpenAI, OpenCodeIcon } from "../Icons";
+import { ClaudeAI, CustomApiIcon, GrokIcon, Icon, KimiIcon, OpenAI, OpenCodeIcon } from "../Icons";
import { PROVIDER_OPTIONS } from "../../session-logic";
export const PROVIDER_ICON_BY_PROVIDER: Partial<Record<ProviderDriverKind, Icon>> = {
@@ -7,6 +7,7 @@ export const PROVIDER_ICON_BY_PROVIDER: Partial<Record<ProviderDriverKind, Icon>
[ProviderDriverKind.make("claudeAgent")]: ClaudeAI,
[ProviderDriverKind.make("opencode")]: OpenCodeIcon,
[ProviderDriverKind.make("opencodeGo")]: OpenCodeIcon,
+ [ProviderDriverKind.make("customOpenai")]: CustomApiIcon,
[ProviderDriverKind.make("grok")]: GrokIcon,
[ProviderDriverKind.make("kimi")]: KimiIcon,
};
diff --git a/apps/web/src/components/icons/CustomApiPresetIcons.tsx b/apps/web/src/components/icons/CustomApiPresetIcons.tsx
new file mode 100644
index 000000000..07635ade9
--- /dev/null
+++ b/apps/web/src/components/icons/CustomApiPresetIcons.tsx
@@ -0,0 +1,105 @@
+import { cn } from "~/lib/utils";
+import { type Icon } from "./iconTypes";
+
+/*
+ * Logos for the Custom API presets, from LobeHub Icons (MIT,
+ * https://github.com/lobehub/lobe-icons). Single-color marks follow the
+ * theme tint; brand-colored marks keep their own palette.
+ */
+
+export const OpenRouterLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" fillRule="evenodd" className={cn("fill-tint", className)}>
+ <path d="M18.654 3.87a5.087 5.087 0 110 10.174L23.7 19.09c.64.641.187 1.737-.72 1.737H8.48a8.479 8.479 0 010-16.958h10.175zM8.479 7.26a5.087 5.087 0 100 10.176 5.087 5.087 0 000-10.175z" />
+ </svg>
+);
+
+export const GroqLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" fillRule="evenodd" className={cn("fill-tint", className)}>
+ <path d="M12.036 2c-3.853-.035-7 3-7.036 6.781-.035 3.782 3.055 6.872 6.908 6.907h2.42v-2.566h-2.292c-2.407.028-4.38-1.866-4.408-4.23-.029-2.362 1.901-4.298 4.308-4.326h.1c2.407 0 4.358 1.915 4.365 4.278v6.305c0 2.342-1.944 4.25-4.323 4.279a4.375 4.375 0 01-3.033-1.252l-1.851 1.818A7 7 0 0012.029 22h.092c3.803-.056 6.858-3.083 6.879-6.816v-6.5C18.907 4.963 15.817 2 12.036 2z" />
+ </svg>
+);
+
+export const TogetherLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" className={className}>
+ <path
+ d="M23.197 4.503A6 6 0 0015 2.307a5.973 5.973 0 00-2.995 4.933l5.996.008v.515h-5.996c.039.937.298 1.87.8 2.74a6 6 0 1010.39-6z"
+ fill="var(--color-brand-together-pink)"
+ />
+ <path
+ d="M.805 4.5A6 6 0 003 12.697a5.972 5.972 0 005.77.127L5.779 7.627l.446-.257 2.997 5.192A6 6 0 10.804 4.5z"
+ fill="var(--color-brand-together-lilac)"
+ />
+ <path
+ d="M12 23.894a6 6 0 005.999-6c0-2.13-1.1-3.996-2.775-5.06l-3.005 5.189-.444-.258 2.997-5.192A6 6 0 1012 23.894z"
+ fill="var(--color-brand-together-orange)"
+ />
+ </svg>
+);
+
+export const DeepSeekLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" className={className}>
+ <path
+ d="M23.748 4.482c-.254-.124-.364.113-.512.234-.051.039-.094.09-.137.136-.372.397-.806.657-1.373.626-.829-.046-1.537.214-2.163.848-.133-.782-.575-1.248-1.247-1.548-.352-.156-.708-.311-.955-.65-.172-.241-.219-.51-.305-.774-.055-.16-.11-.323-.293-.35-.2-.031-.278.136-.356.276-.313.572-.434 1.202-.422 1.84.027 1.436.633 2.58 1.838 3.393.137.093.172.187.129.323-.082.28-.18.552-.266.833-.055.179-.137.217-.329.14a5.526 5.526 0 01-1.736-1.18c-.857-.828-1.631-1.742-2.597-2.458a11.365 11.365 0 00-.689-.471c-.985-.957.13-1.743.388-1.836.27-.098.093-.432-.779-.428-.872.004-1.67.295-2.687.684a3.055 3.055 0 01-.465.137 9.597 9.597 0 00-2.883-.102c-1.885.21-3.39 1.102-4.497 2.623C.082 8.606-.231 10.684.152 12.85c.403 2.284 1.569 4.175 3.36 5.653 1.858 1.533 3.997 2.284 6.438 2.14 1.482-.085 3.133-.284 4.994-1.86.47.234.962.327 1.78.397.63.059 1.236-.03 1.705-.128.735-.156.684-.837.419-.961-2.155-1.004-1.682-.595-2.113-.926 1.096-1.296 2.746-2.642 3.392-7.003.05-.347.007-.565 0-.845-.004-.17.035-.237.23-.256a4.173 4.173 0 001.545-.475c1.396-.763 1.96-2.015 2.093-3.517.02-.23-.004-.467-.247-.588zM11.581 18c-2.089-1.642-3.102-2.183-3.52-2.16-.392.024-.321.471-.235.763.09.288.207.486.371.739.114.167.192.416-.113.603-.673.416-1.842-.14-1.897-.167-1.361-.802-2.5-1.86-3.301-3.307-.774-1.393-1.224-2.887-1.298-4.482-.02-.386.093-.522.477-.592a4.696 4.696 0 011.529-.039c2.132.312 3.946 1.265 5.468 2.774.868.86 1.525 1.887 2.202 2.891.72 1.066 1.494 2.082 2.48 2.914.348.292.625.514.891.677-.802.09-2.14.11-3.054-.614zm1-6.44a.306.306 0 01.415-.287.302.302 0 01.2.288.306.306 0 01-.31.307.303.303 0 01-.304-.308zm3.11 1.596c-.2.081-.399.151-.59.16a1.245 1.245 0 01-.798-.254c-.274-.23-.47-.358-.552-.758a1.73 1.73 0 01.016-.588c.07-.327-.008-.537-.239-.727-.187-.156-.426-.199-.688-.199a.559.559 0 01-.254-.078c-.11-.054-.2-.19-.114-.358.028-.054.16-.186.192-.21.356-.202.767-.136 1.146.016.352.144.618.408 1.001.782.391.451.462.576.685.914.176.265.336.537.445.848.067.195-.019.354-.25.452z"
+ fill="var(--color-brand-deepseek)"
+ />
+ </svg>
+);
+
+export const MistralLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" className={className}>
+ <path
+ d="M3.428 3.4h3.429v3.428H3.428V3.4zm13.714 0h3.43v3.428h-3.43V3.4z"
+ fill="var(--color-brand-mistral-yellow)"
+ />
+ <path
+ d="M3.428 6.828h6.857v3.429H3.429V6.828zm10.286 0h6.857v3.429h-6.857V6.828z"
+ fill="var(--color-brand-mistral-amber)"
+ />
+ <path d="M3.428 10.258h17.144v3.428H3.428v-3.428z" fill="var(--color-brand-mistral-orange)" />
+ <path
+ d="M3.428 13.686h3.429v3.428H3.428v-3.428zm6.858 0h3.429v3.428h-3.429v-3.428zm6.856 0h3.43v3.428h-3.43v-3.428z"
+ fill="var(--color-brand-mistral-red-orange)"
+ />
+ <path
+ d="M0 17.114h10.286v3.429H0v-3.429zm13.714 0H24v3.429H13.714v-3.429z"
+ fill="var(--color-brand-mistral-red)"
+ />
+ </svg>
+);
+
+export const FireworksLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" className={className}>
+ <path
+ clipRule="evenodd"
+ d="M14.8 5l-2.801 6.795L9.195 5H7.397l3.072 7.428a1.64 1.64 0 003.038.002L16.598 5H14.8zm1.196 10.352l5.124-5.244-.699-1.669-5.596 5.739a1.664 1.664 0 00-.343 1.807 1.642 1.642 0 001.516 1.012L16 17l8-.02-.699-1.669-7.303.041h-.002zM2.88 10.104l.699-1.669 5.596 5.739c.468.479.603 1.189.343 1.807a1.643 1.643 0 01-1.516 1.012l-8-.018-.002.002.699-1.669 7.303.042-5.122-5.246z"
+ fill="var(--color-brand-fireworks)"
+ fillRule="evenodd"
+ />
+ </svg>
+);
+
+export const LmStudioLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" fillRule="evenodd" className={cn("fill-tint", className)}>
+ <path
+ d="M2.84 2a1.273 1.273 0 100 2.547h14.107a1.273 1.273 0 100-2.547H2.84zM7.935 5.33a1.273 1.273 0 000 2.548H22.04a1.274 1.274 0 000-2.547H7.935zM3.624 9.935c0-.704.57-1.274 1.274-1.274h14.106a1.274 1.274 0 010 2.547H4.898c-.703 0-1.274-.57-1.274-1.273zM1.273 12.188a1.273 1.273 0 100 2.547H15.38a1.274 1.274 0 000-2.547H1.273zM3.624 16.792c0-.704.57-1.274 1.274-1.274h14.106a1.273 1.273 0 110 2.547H4.898c-.703 0-1.274-.57-1.274-1.273zM13.029 18.849a1.273 1.273 0 100 2.547h9.698a1.273 1.273 0 100-2.547h-9.698z"
+ fillOpacity=".3"
+ />
+ <path d="M2.84 2a1.273 1.273 0 100 2.547h10.287a1.274 1.274 0 000-2.547H2.84zM7.935 5.33a1.273 1.273 0 000 2.548H18.22a1.274 1.274 0 000-2.547H7.935zM3.624 9.935c0-.704.57-1.274 1.274-1.274h10.286a1.273 1.273 0 010 2.547H4.898c-.703 0-1.274-.57-1.274-1.273zM1.273 12.188a1.273 1.273 0 100 2.547H11.56a1.274 1.274 0 000-2.547H1.273zM3.624 16.792c0-.704.57-1.274 1.274-1.274h10.286a1.273 1.273 0 110 2.547H4.898c-.703 0-1.274-.57-1.274-1.273zM13.029 18.849a1.273 1.273 0 100 2.547h5.78a1.273 1.273 0 100-2.547h-5.78z" />
+ </svg>
+);
+
+export const OllamaLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" fillRule="evenodd" className={cn("fill-tint", className)}>
+ <path d="M7.905 1.09c.216.085.411.225.588.41.295.306.544.744.734 1.263.191.522.315 1.1.362 1.68a5.054 5.054 0 012.049-.636l.051-.004c.87-.07 1.73.087 2.48.474.101.053.2.11.297.17.05-.569.172-1.134.36-1.644.19-.52.439-.957.733-1.264a1.67 1.67 0 01.589-.41c.257-.1.53-.118.796-.042.401.114.745.368 1.016.737.248.337.434.769.561 1.287.23.934.27 2.163.115 3.645l.053.04.026.019c.757.576 1.284 1.397 1.563 2.35.435 1.487.216 3.155-.534 4.088l-.018.021.002.003c.417.762.67 1.567.724 2.4l.002.03c.064 1.065-.2 2.137-.814 3.19l-.007.01.01.024c.472 1.157.62 2.322.438 3.486l-.006.039a.651.651 0 01-.747.536.648.648 0 01-.54-.742c.167-1.033.01-2.069-.48-3.123a.643.643 0 01.04-.617l.004-.006c.604-.924.854-1.83.8-2.72-.046-.779-.325-1.544-.8-2.273a.644.644 0 01.18-.886l.009-.006c.243-.159.467-.565.58-1.12a4.229 4.229 0 00-.095-1.974c-.205-.7-.58-1.284-1.105-1.683-.595-.454-1.383-.673-2.38-.61a.653.653 0 01-.632-.371c-.314-.665-.772-1.141-1.343-1.436a3.288 3.288 0 00-1.772-.332c-1.245.099-2.343.801-2.67 1.686a.652.652 0 01-.61.425c-1.067.002-1.893.252-2.497.703-.522.39-.878.935-1.066 1.588a4.07 4.07 0 00-.068 1.886c.112.558.331 1.02.582 1.269l.008.007c.212.207.257.53.109.785-.36.622-.629 1.549-.673 2.44-.05 1.018.186 1.902.719 2.536l.016.019a.643.643 0 01.095.69c-.576 1.236-.753 2.252-.562 3.052a.652.652 0 01-1.269.298c-.243-1.018-.078-2.184.473-3.498l.014-.035-.008-.012a4.339 4.339 0 01-.598-1.309l-.005-.019a5.764 5.764 0 01-.177-1.785c.044-.91.278-1.842.622-2.59l.012-.026-.002-.002c-.293-.418-.51-.953-.63-1.545l-.005-.024a5.352 5.352 0 01.093-2.49c.262-.915.777-1.701 1.536-2.269.06-.045.123-.09.186-.132-.159-1.493-.119-2.73.112-3.67.127-.518.314-.95.562-1.287.27-.368.614-.622 1.015-.737.266-.076.54-.059.797.042zm4.116 9.09c.936 0 1.8.313 2.446.855.63.527 1.005 1.235 1.005 1.94 0 .888-.406 1.58-1.133 2.022-.62.375-1.451.557-2.403.557-1.009 0-1.871-.259-2.493-.734-.617-.47-.963-1.13-.963-1.845 0-.707.398-1.417 1.056-1.946.668-.537 1.55-.849 2.485-.849zm0 .896a3.07 3.07 0 00-1.916.65c-.461.37-.722.835-.722 1.25 0 .428.21.829.61 1.134.455.347 1.124.548 1.943.548.799 0 1.473-.147 1.932-.426.463-.28.7-.686.7-1.257 0-.423-.246-.89-.683-1.256-.484-.405-1.14-.643-1.864-.643zm.662 1.21l.004.004c.12.151.095.37-.056.49l-.292.23v.446a.375.375 0 01-.376.373.375.375 0 01-.376-.373v-.46l-.271-.218a.347.347 0 01-.052-.49.353.353 0 01.494-.051l.215.172.22-.174a.353.353 0 01.49.051zm-5.04-1.919c.478 0 .867.39.867.871a.87.87 0 01-.868.871.87.87 0 01-.867-.87.87.87 0 01.867-.872zm8.706 0c.48 0 .868.39.868.871a.87.87 0 01-.868.871.87.87 0 01-.867-.87.87.87 0 01.867-.872zM7.44 2.3l-.003.002a.659.659 0 00-.285.238l-.005.006c-.138.189-.258.467-.348.832-.17.692-.216 1.631-.124 2.782.43-.128.899-.208 1.404-.237l.01-.001.019-.034c.046-.082.095-.161.148-.239.123-.771.022-1.692-.253-2.444-.134-.364-.297-.65-.453-.813a.628.628 0 00-.107-.09L7.44 2.3zm9.174.04l-.002.001a.628.628 0 00-.107.09c-.156.163-.32.45-.453.814-.29.794-.387 1.776-.23 2.572l.058.097.008.014h.03a5.184 5.184 0 011.466.212c.086-1.124.038-2.043-.128-2.722-.09-.365-.21-.643-.349-.832l-.004-.006a.659.659 0 00-.285-.239h-.004z" />
+ </svg>
+);
+
+export const VllmLogo: Icon = ({ className, ...props }) => (
+ <svg {...props} viewBox="0 0 24 24" className={className}>
+ <path d="M0 4.973h9.324V23L0 4.973z" fill="var(--color-brand-vllm-yellow)" />
+ <path
+ d="M13.986 4.351L22.378 0l-6.216 23H9.324l4.662-18.649z"
+ fill="var(--color-brand-vllm-blue)"
+ />
+ </svg>
+);
diff --git a/apps/web/src/components/icons/ProviderIcons.tsx b/apps/web/src/components/icons/ProviderIcons.tsx
index 0842d0754..d6ff6b574 100644
--- a/apps/web/src/components/icons/ProviderIcons.tsx
+++ b/apps/web/src/components/icons/ProviderIcons.tsx
@@ -67,3 +67,21 @@ export const OpenCodeIcon: Icon = (props) => (
</defs>
</svg>
);
+
+/** Neutral plug glyph for user-supplied endpoints, which have no brand of their own. */
+export const CustomApiIcon: Icon = ({ className, ...props }) => (
+ <svg
+ {...props}
+ viewBox="0 0 24 24"
+ fill="none"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ className={cn("stroke-tint", className)}
+ >
+ <path d="M12 22v-5" />
+ <path d="M15 8V2" />
+ <path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z" />
+ <path d="M9 8V2" />
+ </svg>
+);
diff --git a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
index 719ae5f77..50125c4d1 100644
--- a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
+++ b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
@@ -38,6 +38,14 @@ import {
type WizardNavigation,
} from "./AddProviderInstanceDialog.logic";
import { AddProviderInstanceWizardSteps } from "./AddProviderInstanceWizardSteps";
+import { CustomApiKeyDraftField } from "./CustomApiKeyField";
+import { CustomApiPresetPicker } from "./CustomApiPresetPicker";
+import {
+ customApiKeyHint,
+ OTHER_CUSTOM_API_PRESET,
+ withCustomApiKey,
+ type CustomApiPreset,
+} from "./customApiPresets";
const PROVIDER_ACCENT_SWATCHES = [
"#2563eb",
@@ -74,6 +82,8 @@ const INSTANCE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
+const CUSTOM_API_DRIVER_KIND = ProviderDriverKind.make("customOpenai");
+
const DEFAULT_DRIVER_OPTION = DRIVER_OPTIONS[0]!;
const EMPTY_CONFIG_DRAFT: ProviderConfig = {};
@@ -152,6 +162,10 @@ export function AddProviderInstanceDialog({
);
const [label, setLabel] = useState("");
+ // A preset names the instance until the user types a label of their own.
+ const [labelEdited, setLabelEdited] = useState(false);
+ const [customApiPreset, setCustomApiPreset] = useState<CustomApiPreset>(OTHER_CUSTOM_API_PRESET);
+ const [customApiKey, setCustomApiKey] = useState("");
const [accentColor, setAccentColor] = useState<string>("");
const [instanceIdOverride, setInstanceIdOverride] = useState<string | null>(null);
// Driver-specific config drafts keyed by driver so toggling between drivers
@@ -195,6 +209,24 @@ export function AddProviderInstanceDialog({
});
};
+ const chooseCustomApiPreset = (preset: CustomApiPreset) => {
+ // A key belongs to one service; never send it to the next endpoint.
+ if (preset.id !== customApiPreset.id) setCustomApiKey("");
+
+ setCustomApiPreset(preset);
+
+ if (!labelEdited) setLabel(preset === OTHER_CUSTOM_API_PRESET ? "" : preset.label);
+
+ setConfigByDriver((existing) => {
+ const { baseUrl: _omit, ...rest } = existing[CUSTOM_API_DRIVER_KIND] ?? {};
+
+ return {
+ ...existing,
+ [CUSTOM_API_DRIVER_KIND]: preset.baseUrl ? { ...rest, baseUrl: preset.baseUrl } : rest,
+ };
+ });
+ };
+
const applyWizardNavigation = (navigation: WizardNavigation) => {
if (navigation.kind === "blocked") {
setHasAttemptedSubmit(true);
@@ -220,12 +252,15 @@ export function AddProviderInstanceDialog({
const hasConfig = Object.keys(config).length > 0;
const normalizedAccentColor = normalizeProviderAccentColor(accentColor);
+ const environment = driver === CUSTOM_API_DRIVER_KIND ? withCustomApiKey([], customApiKey) : [];
+
const nextInstance: ProviderInstanceConfig = {
driver,
enabled: true,
...(label.trim().length > 0 ? { displayName: label.trim() } : {}),
...(normalizedAccentColor ? { accentColor: normalizedAccentColor } : {}),
...(hasConfig ? { config } : {}),
+ ...(environment.length > 0 ? { environment } : {}),
};
// `ProviderInstanceId.make` revalidates the slug; we've already checked
@@ -342,6 +377,14 @@ export function AddProviderInstanceDialog({
);
})}
</RadioGroup>
+ {driver === CUSTOM_API_DRIVER_KIND ? (
+ <div className="mt-3">
+ <CustomApiPresetPicker
+ value={customApiPreset.id}
+ onChange={chooseCustomApiPreset}
+ />
+ </div>
+ ) : null}
</div>
<label className={cn("grid gap-2", wizardStep !== 1 && "hidden")}>
@@ -350,7 +393,10 @@ export function AddProviderInstanceDialog({
surface="background"
placeholder="e.g. Work"
value={label}
- onChange={(event) => setLabel(event.target.value)}
+ onChange={(event) => {
+ setLabel(event.target.value);
+ setLabelEdited(true);
+ }}
/>
<span className="text-11px text-muted-foreground">
Shown in the provider list. Optional.
@@ -434,6 +480,15 @@ export function AddProviderInstanceDialog({
variant="dialog"
onChange={setConfigDraft}
/>
+ {driver === CUSTOM_API_DRIVER_KIND ? (
+ <CustomApiKeyDraftField
+ id="add-provider-custom-api-key"
+ value={customApiKey}
+ required={customApiPreset.key.kind === "required"}
+ hint={customApiKeyHint(customApiPreset)}
+ onChange={setCustomApiKey}
+ />
+ ) : null}
</div>
) : wizardStep === 2 ? (
<div className="grid gap-2">
diff --git a/apps/web/src/components/settings/CustomApiKeyField.tsx b/apps/web/src/components/settings/CustomApiKeyField.tsx
new file mode 100644
index 000000000..1c0334a3d
--- /dev/null
+++ b/apps/web/src/components/settings/CustomApiKeyField.tsx
@@ -0,0 +1,85 @@
+import type { ProviderInstanceEnvironmentVariable } from "@akeru/contracts";
+
+import { Button } from "../ui/button";
+import { DraftInput } from "../ui/draft-input";
+import { Input } from "../ui/input";
+
+function KeyLabel(props: { readonly required: boolean }) {
+ return (
+ <span className="text-xs font-medium text-foreground">
+ API key{" "}
+ {props.required ? null : <span className="font-normal text-muted-foreground">optional</span>}
+ </span>
+ );
+}
+
+/** Key field for a Custom API instance that is not saved yet. */
+export function CustomApiKeyDraftField(props: {
+ readonly id: string;
+ readonly value: string;
+ readonly hint: string;
+ readonly required: boolean;
+ readonly onChange: (value: string) => void;
+}) {
+ return (
+ <label htmlFor={props.id} className="grid gap-1.5">
+ <KeyLabel required={props.required} />
+ <Input
+ id={props.id}
+ surface="background"
+ type="password"
+ autoComplete="off"
+ spellCheck={false}
+ value={props.value}
+ onChange={(event) => props.onChange(event.target.value)}
+ placeholder="sk-…"
+ />
+ <span className="text-11px text-muted-foreground">{props.hint}</span>
+ </label>
+ );
+}
+
+/**
+ * Key field on a saved instance. The server redacts a stored key, so the
+ * input stays empty and says a key is stored; committing an empty value
+ * leaves the stored key alone, and Remove clears it.
+ */
+export function CustomApiKeyField(props: {
+ readonly id: string;
+ readonly variable: ProviderInstanceEnvironmentVariable | undefined;
+ readonly hint: string;
+ readonly required: boolean;
+ readonly onCommit: (value: string) => void;
+ readonly onRemove: () => void;
+}) {
+ const stored =
+ props.variable !== undefined && (props.variable.valueRedacted || props.variable.value !== "");
+
+ return (
+ <div>
+ <div className="flex items-center justify-between gap-3">
+ <label htmlFor={props.id}>
+ <KeyLabel required={props.required} />
+ </label>
+ {stored ? (
+ <Button type="button" size="xs" variant="ghost" onClick={props.onRemove}>
+ Remove key
+ </Button>
+ ) : null}
+ </div>
+ <DraftInput
+ id={props.id}
+ className="mt-1.5"
+ type="password"
+ autoComplete="off"
+ spellCheck={false}
+ value=""
+ onCommit={(value) => {
+ if (value.trim().length > 0) props.onCommit(value);
+ }}
+ placeholder={stored ? "Key stored securely. Type a new one to replace it." : "sk-…"}
+ />
+ <span className="mt-1 block text-xs text-muted-foreground">{props.hint}</span>
+ </div>
+ );
+}
diff --git a/apps/web/src/components/settings/CustomApiPresetPicker.tsx b/apps/web/src/components/settings/CustomApiPresetPicker.tsx
new file mode 100644
index 000000000..5db3cf593
--- /dev/null
+++ b/apps/web/src/components/settings/CustomApiPresetPicker.tsx
@@ -0,0 +1,48 @@
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+
+import { RadioGroup } from "../ui/radio-group";
+import { CUSTOM_API_PRESETS, type CustomApiPreset } from "./customApiPresets";
+
+/** Starting points for a Custom API instance. Picking one fills in its base URL. */
+export function CustomApiPresetPicker(props: {
+ readonly value: CustomApiPreset["id"];
+ readonly onChange: (preset: CustomApiPreset) => void;
+}) {
+ return (
+ <div className="grid gap-2">
+ <div id="custom-api-preset-label" className="text-sm font-medium text-foreground">
+ What are you connecting to?
+ </div>
+ <RadioGroup
+ value={props.value}
+ onValueChange={(value) => {
+ const preset = CUSTOM_API_PRESETS.find((entry) => entry.id === value);
+
+ if (preset) props.onChange(preset);
+ }}
+ aria-labelledby="custom-api-preset-label"
+ className="grid grid-cols-1 gap-2 sm:grid-cols-2"
+ >
+ {CUSTOM_API_PRESETS.map((preset) => {
+ const Logo = preset.icon;
+
+ return (
+ <RadioPrimitive.Root
+ key={preset.id}
+ value={preset.id}
+ className="flex cursor-pointer items-center gap-3 rounded-lg bg-card px-3 py-2.5 text-left outline-none ring-1 ring-tint/5 hover:bg-option-hover focus-visible:ring-2 focus-visible:ring-ring data-checked:bg-primary/8 data-checked:ring-2 data-checked:ring-primary data-checked:hover:bg-primary/8 dark:bg-tint/3 dark:hover:bg-tint/5 dark:data-checked:bg-primary/15 dark:data-checked:hover:bg-primary/15"
+ >
+ <span className="grid size-8 shrink-0 place-items-center rounded-md bg-background ring-1 ring-tint/8">
+ <Logo className="size-4.5" aria-hidden />
+ </span>
+ <span className="grid min-w-0">
+ <span className="truncate text-sm font-medium text-foreground">{preset.label}</span>
+ <span className="truncate text-xs text-muted-foreground">{preset.tagline}</span>
+ </span>
+ </RadioPrimitive.Root>
+ );
+ })}
+ </RadioGroup>
+ </div>
+ );
+}
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.test.ts b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
index 28ade0705..6fed7c054 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.test.ts
+++ b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
@@ -33,4 +33,18 @@ describe("deriveProviderModelsForDisplay", () => {
}).map((model) => model.slug),
).toEqual(["server-model", "kept-custom"]);
});
+
+ it("does not repeat a hand-added slug the live catalog already reports", () => {
+ const liveModels: ReadonlyArray<ServerProviderModel> = [
+ { slug: "gpt-4o-mini", name: "gpt-4o-mini", isCustom: false, capabilities: null },
+ { slug: "local-only", name: "local-only", isCustom: true, capabilities: null },
+ ];
+
+ expect(
+ deriveProviderModelsForDisplay({
+ liveModels,
+ customModels: ["gpt-4o-mini", "local-only"],
+ }).map((model) => model.slug),
+ ).toEqual(["gpt-4o-mini", "local-only"]);
+ });
});
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index d96b87651..e05bd4cf7 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -17,7 +17,7 @@ import {
type ProviderInstanceConfig,
type ProviderInstanceEnvironmentVariable,
type ProviderInstanceId,
- type ProviderDriverKind,
+ ProviderDriverKind,
type ServerProvider,
} from "@akeru/contracts";
import { cn } from "../../lib/utils";
@@ -33,7 +33,7 @@ import { Switch } from "../ui/switch";
import { stackedThreadToast, toastManager } from "../ui/toast";
import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
import type { DriverOption } from "./providerDriverMeta";
-import { ProviderSettingsForm } from "./ProviderSettingsForm";
+import { ProviderSettingsForm, readProviderConfigString } from "./ProviderSettingsForm";
import { ProviderModelsSection } from "./ProviderModelsSection";
import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
import { ProviderAccentColorPicker } from "./ProviderAccentColorPicker";
@@ -45,6 +45,16 @@ import {
type ProviderStatusKey,
} from "./providerStatus";
import { ProviderEnvironmentSection } from "./ProviderEnvironmentSection";
+import { CustomApiKeyField } from "./CustomApiKeyField";
+import {
+ customApiKeyHint,
+ customApiKeyLeavesEndpoint,
+ customApiPresetForBaseUrl,
+ readCustomApiKey,
+ withCustomApiKey,
+ withoutCustomApiKey,
+ withStoredCustomApiKey,
+} from "./customApiPresets";
import { ProviderAuthEmail } from "./ProviderAuthEmail";
import {
readConfigStringArray,
@@ -210,9 +220,43 @@ export function ProviderInstanceCard({
onUpdate(normalized ? { ...rest, accentColor: normalized } : rest);
};
+ // Every edit that can move a Custom API endpoint goes through here, so a
+ // stored key is never probed against a host it was not saved for.
+ const commitEndpointEdit = (next: ProviderInstanceConfig) => {
+ const dropsCustomApiKey =
+ instance.driver === ProviderDriverKind.make("customOpenai") &&
+ readCustomApiKey(next.environment ?? []) !== undefined &&
+ customApiKeyLeavesEndpoint(
+ {
+ baseUrl: readProviderConfigString(instance.config, "baseUrl"),
+ environment: instance.environment ?? [],
+ },
+ {
+ baseUrl: readProviderConfigString(next.config, "baseUrl"),
+ environment: next.environment ?? [],
+ },
+ );
+
+ if (!dropsCustomApiKey) {
+ onUpdate(next);
+
+ return;
+ }
+
+ // Save the new address and drop the old key together.
+ const environment = withoutCustomApiKey(next.environment ?? []);
+ const { environment: _omitEnvironment, ...withoutEnvironment } = next;
+ onUpdate(environment.length > 0 ? { ...next, environment } : withoutEnvironment);
+ toastManager.add({
+ type: "info",
+ title: "API key removed",
+ description: "The new address is a different service. Paste its key to connect.",
+ });
+ };
+
const updateConfig = (nextConfig: ProviderConfig | undefined) => {
const { config: _omit, ...rest } = instance;
- onUpdate(nextConfig !== undefined ? { ...rest, config: nextConfig } : rest);
+ commitEndpointEdit(nextConfig !== undefined ? { ...rest, config: nextConfig } : rest);
};
const updateCustomModels = (next: ReadonlyArray<string>) => {
@@ -221,12 +265,26 @@ export function ProviderInstanceCard({
onUpdate({ ...rest, config: nextConfig });
};
- const updateEnvironment = (environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>) => {
+ const withEnvironment = (environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>) => {
const cleaned = environment.filter((variable) => variable.name.trim().length > 0);
const { environment: _omit, ...rest } = instance;
- onUpdate(cleaned.length > 0 ? { ...rest, environment: cleaned } : rest);
+
+ return cleaned.length > 0 ? { ...rest, environment: cleaned } : rest;
};
+ const updateEnvironment = (environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>) =>
+ onUpdate(withEnvironment(environment));
+
+ // Custom API keeps its key in a dedicated field, so the generic variable
+ // table hides it and merges it back on edit.
+ const isCustomApi = instance.driver === ProviderDriverKind.make("customOpenai");
+ const environment = instance.environment ?? [];
+ const customApiKey = isCustomApi ? readCustomApiKey(environment) : undefined;
+
+ const customApiPreset = customApiPresetForBaseUrl(
+ readProviderConfigString(instance.config, "baseUrl"),
+ );
+
const titleIconNode = driverKind ? (
<ProviderInstanceIcon
driverKind={driverKind}
@@ -480,8 +538,14 @@ export function ProviderInstanceCard({
<div>
<ProviderEnvironmentSection
- environment={instance.environment ?? []}
- onChange={updateEnvironment}
+ environment={isCustomApi ? withoutCustomApiKey(environment) : environment}
+ onChange={(next) =>
+ commitEndpointEdit(
+ withEnvironment(
+ isCustomApi ? withStoredCustomApiKey(next, customApiKey) : next,
+ ),
+ )
+ }
/>
</div>
@@ -495,6 +559,17 @@ export function ProviderInstanceCard({
/>
) : null}
+ {isCustomApi ? (
+ <CustomApiKeyField
+ id={`provider-instance-${instanceId}-api-key`}
+ variable={customApiKey}
+ required={customApiPreset.key.kind === "required"}
+ hint={customApiKeyHint(customApiPreset)}
+ onCommit={(value) => updateEnvironment(withCustomApiKey(environment, value))}
+ onRemove={() => updateEnvironment(withCustomApiKey(environment, ""))}
+ />
+ ) : null}
+
{driverOption !== undefined ? (
<ProviderModelsSection
instanceId={instanceId}
diff --git a/apps/web/src/components/settings/ProviderModelsSection.test.ts b/apps/web/src/components/settings/ProviderModelsSection.test.ts
index 4d753a725..72133556e 100644
--- a/apps/web/src/components/settings/ProviderModelsSection.test.ts
+++ b/apps/web/src/components/settings/ProviderModelsSection.test.ts
@@ -4,14 +4,24 @@ import { renderToStaticMarkup } from "react-dom/server";
import { describe, expect, it, vi } from "vite-plus/test";
import { ProviderDriverKind, ProviderInstanceId, type ServerProviderModel } from "@akeru/contracts";
+/** Base UI trigger wrappers read `nativeEvent` before calling the handler. */
+type TriggerClick = { readonly nativeEvent: object };
+
const mocks = vi.hoisted(() => ({
- buttons: new Map<string, { onClick?: () => void }>(),
+ buttons: new Map<string, { onClick?: (event?: TriggerClick) => void }>(),
+ labelledButtons: new Map<string, { onClick?: (event?: TriggerClick) => void }>(),
}));
vi.mock("../ui/button", () => ({
- Button: (props: { children: ReactNode; onClick?: () => void }) => {
+ Button: (props: {
+ children: ReactNode;
+ onClick?: (event?: TriggerClick) => void;
+ "aria-label"?: string;
+ }) => {
if (Predicate.isString(props.children)) mocks.buttons.set(props.children, props);
+ if (props["aria-label"]) mocks.labelledButtons.set(props["aria-label"], props);
+
return null;
},
}));
@@ -50,26 +60,35 @@ describe("ProviderModelsSection bulk visibility control", () => {
function renderSection(input: {
models: ReadonlyArray<ServerProviderModel>;
hiddenModels?: ReadonlyArray<string>;
+ customModels?: ReadonlyArray<string>;
+ favoriteModels?: ReadonlyArray<string>;
+ modelOrder?: ReadonlyArray<string>;
}) {
mocks.buttons.clear();
+ mocks.labelledButtons.clear();
const onHiddenModelsChange = vi.fn();
+ const onChange = vi.fn();
+ const onFavoriteModelsChange = vi.fn();
+ const onModelOrderChange = vi.fn();
renderToStaticMarkup(
createElement(ProviderModelsSection, {
instanceId: ProviderInstanceId.make("codex"),
driverKind: ProviderDriverKind.make("codex"),
models: input.models,
- customModels: input.models.flatMap((entry) => (entry.isCustom ? [entry.slug] : [])),
+ customModels:
+ input.customModels ??
+ input.models.flatMap((entry) => (entry.isCustom ? [entry.slug] : [])),
hiddenModels: input.hiddenModels ?? [],
- favoriteModels: [],
- modelOrder: [],
- onChange: vi.fn(),
+ favoriteModels: input.favoriteModels ?? [],
+ modelOrder: input.modelOrder ?? [],
+ onChange,
onHiddenModelsChange,
- onFavoriteModelsChange: vi.fn(),
- onModelOrderChange: vi.fn(),
+ onFavoriteModelsChange,
+ onModelOrderChange,
}),
);
- return { onHiddenModelsChange };
+ return { onHiddenModelsChange, onChange, onFavoriteModelsChange, onModelOrderChange };
}
it("omits the bulk control when every model is custom", () => {
@@ -100,4 +119,40 @@ describe("ProviderModelsSection bulk visibility control", () => {
mocks.buttons.get("Enable all")?.onClick?.();
expect(onHiddenModelsChange).toHaveBeenCalledWith(["legacy", "custom"]);
});
+
+ it("removes a hand-added model the endpoint also reports and keeps its preferences", () => {
+ const { onChange, onFavoriteModelsChange, onModelOrderChange } = renderSection({
+ models: [model("gpt-4o-mini"), model("llama-3.3")],
+ customModels: ["gpt-4o-mini"],
+ favoriteModels: ["gpt-4o-mini"],
+ modelOrder: ["gpt-4o-mini", "llama-3.3"],
+ });
+
+ const remove = mocks.labelledButtons.get("Remove gpt-4o-mini");
+ expect(remove).toBeDefined();
+ // The tooltip trigger wraps the handler, so it reads `nativeEvent` first.
+ remove?.onClick?.({ nativeEvent: {} });
+ expect(onChange).toHaveBeenCalledWith([]);
+ expect(onFavoriteModelsChange).not.toHaveBeenCalled();
+ expect(onModelOrderChange).not.toHaveBeenCalled();
+ });
+
+ it("clears the preferences of a hand-added model that leaves the list", () => {
+ const { onChange, onFavoriteModelsChange, onModelOrderChange } = renderSection({
+ models: [model("llama-3.3"), model("my-model", true)],
+ favoriteModels: ["my-model"],
+ modelOrder: ["my-model", "llama-3.3"],
+ });
+
+ mocks.labelledButtons.get("Remove my-model")?.onClick?.({ nativeEvent: {} });
+ expect(onChange).toHaveBeenCalledWith([]);
+ expect(onFavoriteModelsChange).toHaveBeenCalledWith([]);
+ expect(onModelOrderChange).toHaveBeenCalledWith(["llama-3.3"]);
+ });
+
+ it("leaves catalog-only models without a remove control", () => {
+ renderSection({ models: [model("gpt-4o-mini")], customModels: [] });
+
+ expect(mocks.labelledButtons.has("Remove gpt-4o-mini")).toBe(false);
+ });
});
diff --git a/apps/web/src/components/settings/ProviderModelsSection.tsx b/apps/web/src/components/settings/ProviderModelsSection.tsx
index e8dfea19c..d8095a4b1 100644
--- a/apps/web/src/components/settings/ProviderModelsSection.tsx
+++ b/apps/web/src/components/settings/ProviderModelsSection.tsx
@@ -36,6 +36,7 @@ const CUSTOM_MODEL_PLACEHOLDER_BY_KIND: Partial<Record<ProviderDriverKind, strin
[ProviderDriverKind.make("kimi")]: "k3-256k",
[ProviderDriverKind.make("opencode")]: "openai/gpt-5",
[ProviderDriverKind.make("opencodeGo")]: "gpt-5.6-luna",
+ [ProviderDriverKind.make("customOpenai")]: "gpt-4o-mini",
};
interface ProviderModelsSectionProps {
@@ -118,6 +119,10 @@ export function ProviderModelsSection({
const listRef = useRef<HTMLDivElement | null>(null);
const hiddenModelSet = useMemo(() => new Set(hiddenModels), [hiddenModels]);
const favoriteModelSet = useMemo(() => new Set(favoriteModels), [favoriteModels]);
+ // A slug can be both hand-added and reported by the endpoint (a catalog that
+ // later gained the model). It renders as one row, and that row still needs the
+ // remove control for the saved entry.
+ const savedCustomModelSet = useMemo(() => new Set(customModels), [customModels]);
const orderedModels = useMemo(() => {
return sortModelsForProviderInstance(models, {
@@ -182,10 +187,16 @@ export function ProviderModelsSection({
setTimeout(() => observer.disconnect(), 2_000);
};
- const handleRemove = (slug: string) => {
+ // A hand-added entry for a model the endpoint also lists only drops the
+ // entry; the model stays, so its favorite and position stay with it.
+ const handleRemove = (slug: string, stillListed: boolean) => {
onChange(customModels.filter((model) => model !== slug));
- onModelOrderChange(modelOrder.filter((model) => model !== slug));
- onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
+
+ if (!stillListed) {
+ onModelOrderChange(modelOrder.filter((model) => model !== slug));
+ onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
+ }
+
setError(null);
};
@@ -331,7 +342,7 @@ export function ProviderModelsSection({
</Tooltip>
) : null}
{isHidden ? <span className="text-10px text-muted-foreground">hidden</span> : null}
- {model.isCustom ? (
+ {model.isCustom || savedCustomModelSet.has(model.slug) ? (
<span className="text-10px text-muted-foreground">custom</span>
) : null}
</div>
@@ -411,7 +422,7 @@ export function ProviderModelsSection({
</TooltipPopup>
</Tooltip>
) : null}
- {model.isCustom ? (
+ {model.isCustom || savedCustomModelSet.has(model.slug) ? (
<Tooltip>
<TooltipTrigger
render={
@@ -419,7 +430,7 @@ export function ProviderModelsSection({
size="icon-micro"
variant="ghost-muted"
aria-label={`Remove ${model.slug}`}
- onClick={() => handleRemove(model.slug)}
+ onClick={() => handleRemove(model.slug, !model.isCustom)}
/>
}
>
diff --git a/apps/web/src/components/settings/customApiPresets.test.ts b/apps/web/src/components/settings/customApiPresets.test.ts
new file mode 100644
index 000000000..f7ca6fe4d
--- /dev/null
+++ b/apps/web/src/components/settings/customApiPresets.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ CUSTOM_API_KEY_ENV,
+ CUSTOM_API_PRESETS,
+ customApiKeyHint,
+ customApiKeyLeavesEndpoint,
+ customApiPresetForBaseUrl,
+ OTHER_CUSTOM_API_PRESET,
+ withCustomApiKey,
+ withStoredCustomApiKey,
+} from "./customApiPresets";
+
+function preset(id: string) {
+ const match = CUSTOM_API_PRESETS.find((entry) => entry.id === id);
+
+ if (!match) throw new Error(`missing preset ${id}`);
+
+ return match;
+}
+
+describe("customApiPresetForBaseUrl", () => {
+ it("matches a preset despite case and a trailing slash", () => {
+ expect(customApiPresetForBaseUrl("HTTPS://openrouter.ai/api/v1/").id).toBe("openrouter");
+ });
+
+ it("falls back to Other for an unknown or empty URL", () => {
+ expect(customApiPresetForBaseUrl("https://llm.internal/v1")).toBe(OTHER_CUSTOM_API_PRESET);
+ expect(customApiPresetForBaseUrl(" ")).toBe(OTHER_CUSTOM_API_PRESET);
+ });
+});
+
+describe("customApiKeyHint", () => {
+ it("points a hosted service at its key page", () => {
+ expect(customApiKeyHint(preset("openrouter"))).toBe(
+ "Required. Create one at openrouter.ai/settings/keys.",
+ );
+ });
+
+ it("tells local servers that no key is needed", () => {
+ expect(customApiKeyHint(preset("ollama"))).toBe("Not needed for this server. Leave it empty.");
+ });
+});
+
+describe("withCustomApiKey", () => {
+ const other = { name: "HTTP_PROXY", value: "http://proxy", sensitive: false };
+
+ it("adds the key as a sensitive variable", () => {
+ expect(withCustomApiKey([other], " sk-test ")).toEqual([
+ other,
+ { name: CUSTOM_API_KEY_ENV, value: "sk-test", sensitive: true },
+ ]);
+ });
+
+ it("replaces a stored key instead of duplicating it", () => {
+ const stored = withCustomApiKey([other], "sk-old");
+
+ expect(withCustomApiKey(stored, "sk-new")).toEqual([
+ other,
+ { name: CUSTOM_API_KEY_ENV, value: "sk-new", sensitive: true },
+ ]);
+ });
+
+ it("removes the key when the value is empty", () => {
+ expect(withCustomApiKey(withCustomApiKey([other], "sk-old"), "")).toEqual([other]);
+ });
+});
+
+describe("withStoredCustomApiKey", () => {
+ const other = { name: "HTTP_PROXY", value: "http://proxy", sensitive: false };
+ const stored = { name: CUSTOM_API_KEY_ENV, value: "", sensitive: true, valueRedacted: true };
+
+ it("keeps the stored key through ordinary environment edits", () => {
+ expect(withStoredCustomApiKey([other], stored)).toEqual([other, stored]);
+ });
+
+ it("ignores a generic row that reuses the reserved name", () => {
+ const collision = { name: CUSTOM_API_KEY_ENV, value: "", sensitive: true };
+
+ expect(withStoredCustomApiKey([other, collision], stored)).toEqual([other, stored]);
+ expect(withStoredCustomApiKey([other, collision], undefined)).toEqual([other]);
+ });
+});
+
+const endpoint = (baseUrl: string, override?: { value: string; valueRedacted?: boolean }) => ({
+ baseUrl,
+ environment: override ? [{ name: "CUSTOM_OPENAI_BASE_URL", sensitive: false, ...override }] : [],
+});
+
+describe("customApiKeyLeavesEndpoint", () => {
+ const leaves = (previous: string, next: string) =>
+ customApiKeyLeavesEndpoint(endpoint(previous), endpoint(next));
+
+ it("keeps the key when only the path changes or the scheme upgrades", () => {
+ expect(leaves("https://openrouter.ai/api/v1", "https://openrouter.ai/api/v2")).toBe(false);
+ expect(leaves("http://localhost:1234/v1", "https://localhost:1234/v1")).toBe(false);
+ });
+
+ it("drops the key when the base URL moves to another host", () => {
+ expect(leaves("https://openrouter.ai/api/v1", "https://api.groq.com/openai/v1")).toBe(true);
+ expect(leaves("http://localhost:1234/v1", "http://localhost:11434/v1")).toBe(true);
+ expect(leaves("https://openrouter.ai/api/v1", "")).toBe(true);
+ });
+
+ it("drops the key when the base URL downgrades from HTTPS to HTTP", () => {
+ expect(leaves("https://openrouter.ai/api/v1", "http://openrouter.ai/api/v1")).toBe(true);
+ });
+
+ it("keeps the key when an instance gets its first base URL", () => {
+ expect(leaves("", "https://openrouter.ai/api/v1")).toBe(false);
+ });
+
+ it("follows the CUSTOM_OPENAI_BASE_URL override the driver sends to", () => {
+ const configured = "https://openrouter.ai/api/v1";
+
+ expect(
+ customApiKeyLeavesEndpoint(
+ endpoint(configured),
+ endpoint(configured, { value: "https://evil.example/v1" }),
+ ),
+ ).toBe(true);
+ expect(
+ customApiKeyLeavesEndpoint(
+ endpoint(configured, { value: "https://evil.example/v1" }),
+ endpoint("https://api.groq.com/openai/v1", { value: "https://evil.example/v1" }),
+ ),
+ ).toBe(false);
+ });
+
+ it("drops the key when a redacted override changes and keeps it when untouched", () => {
+ const redacted = { value: "", valueRedacted: true };
+ const configured = "https://openrouter.ai/api/v1";
+
+ expect(
+ customApiKeyLeavesEndpoint(
+ endpoint(configured, redacted),
+ endpoint(configured, { value: "https://openrouter.ai/api/v1" }),
+ ),
+ ).toBe(true);
+ expect(
+ customApiKeyLeavesEndpoint(endpoint(configured, redacted), endpoint(configured, redacted)),
+ ).toBe(false);
+ });
+
+ it("drops the key when the base URL moves behind an unreadable override", () => {
+ // A redacted override may be blank, which sends requests to the base URL.
+ const redacted = { value: "", valueRedacted: true };
+
+ expect(
+ customApiKeyLeavesEndpoint(
+ endpoint("https://openrouter.ai/api/v1", redacted),
+ endpoint("https://evil.example/v1", redacted),
+ ),
+ ).toBe(true);
+ });
+
+ it("follows the last override row, as the driver does", () => {
+ const configured = "https://openrouter.ai/api/v1";
+
+ const withOverrides = (last: string) => ({
+ baseUrl: configured,
+ environment: [
+ { name: "CUSTOM_OPENAI_BASE_URL", value: configured, sensitive: false },
+ { name: "CUSTOM_OPENAI_BASE_URL", value: last, sensitive: false },
+ ],
+ });
+
+ expect(
+ customApiKeyLeavesEndpoint(
+ withOverrides("https://openrouter.ai/api/v1"),
+ withOverrides("https://evil.example/v1"),
+ ),
+ ).toBe(true);
+ });
+});
diff --git a/apps/web/src/components/settings/customApiPresets.ts b/apps/web/src/components/settings/customApiPresets.ts
new file mode 100644
index 000000000..336d15b11
--- /dev/null
+++ b/apps/web/src/components/settings/customApiPresets.ts
@@ -0,0 +1,257 @@
+import type { ProviderInstanceEnvironmentVariable } from "@akeru/contracts";
+
+import { CustomApiIcon, type Icon } from "../Icons";
+import {
+ DeepSeekLogo,
+ FireworksLogo,
+ GroqLogo,
+ LmStudioLogo,
+ MistralLogo,
+ OllamaLogo,
+ OpenRouterLogo,
+ TogetherLogo,
+ VllmLogo,
+} from "../icons/CustomApiPresetIcons";
+
+/** The instance variable the Custom API driver reads its key from. */
+export const CUSTOM_API_KEY_ENV = "CUSTOM_OPENAI_API_KEY";
+
+export interface CustomApiPreset {
+ readonly id: string;
+ readonly label: string;
+ readonly tagline: string;
+ readonly icon: Icon;
+ /** Empty for "Other", where the user types the URL. */
+ readonly baseUrl: string;
+ readonly key:
+ | { readonly kind: "required"; readonly url: string }
+ | { readonly kind: "optional" }
+ | { readonly kind: "none" };
+}
+
+/**
+ * Services the add dialog offers as one-click starting points. Local entries
+ * resolve on the machine running the environment server, not the browser.
+ */
+export const CUSTOM_API_PRESETS: readonly CustomApiPreset[] = [
+ {
+ id: "openrouter",
+ label: "OpenRouter",
+ tagline: "Hundreds of models, one key",
+ icon: OpenRouterLogo,
+ baseUrl: "https://openrouter.ai/api/v1",
+ key: { kind: "required", url: "https://openrouter.ai/settings/keys" },
+ },
+ {
+ id: "groq",
+ label: "Groq",
+ tagline: "Fast hosted open models",
+ icon: GroqLogo,
+ baseUrl: "https://api.groq.com/openai/v1",
+ key: { kind: "required", url: "https://console.groq.com/keys" },
+ },
+ {
+ id: "together",
+ label: "Together AI",
+ tagline: "Hosted open models",
+ icon: TogetherLogo,
+ baseUrl: "https://api.together.ai/v1",
+ key: { kind: "required", url: "https://api.together.ai/settings/api-keys" },
+ },
+ {
+ id: "deepseek",
+ label: "DeepSeek",
+ tagline: "DeepSeek's own API",
+ icon: DeepSeekLogo,
+ baseUrl: "https://api.deepseek.com/v1",
+ key: { kind: "required", url: "https://platform.deepseek.com/api_keys" },
+ },
+ {
+ id: "mistral",
+ label: "Mistral",
+ tagline: "Mistral and Codestral",
+ icon: MistralLogo,
+ baseUrl: "https://api.mistral.ai/v1",
+ key: { kind: "required", url: "https://console.mistral.ai/api-keys" },
+ },
+ {
+ id: "fireworks",
+ label: "Fireworks",
+ tagline: "Hosted open models",
+ icon: FireworksLogo,
+ baseUrl: "https://api.fireworks.ai/inference/v1",
+ key: { kind: "required", url: "https://fireworks.ai/account/api-keys" },
+ },
+ {
+ id: "lmstudio",
+ label: "LM Studio",
+ tagline: "Local models, no key",
+ icon: LmStudioLogo,
+ baseUrl: "http://localhost:1234/v1",
+ key: { kind: "none" },
+ },
+ {
+ id: "ollama",
+ label: "Ollama",
+ tagline: "Local models, no key",
+ icon: OllamaLogo,
+ baseUrl: "http://localhost:11434/v1",
+ key: { kind: "none" },
+ },
+ {
+ id: "vllm",
+ label: "vLLM",
+ tagline: "Your own inference server",
+ icon: VllmLogo,
+ baseUrl: "http://localhost:8000/v1",
+ key: { kind: "optional" },
+ },
+ {
+ id: "other",
+ label: "Other",
+ tagline: "Any OpenAI-compatible URL",
+ icon: CustomApiIcon,
+ baseUrl: "",
+ key: { kind: "optional" },
+ },
+];
+
+export const OTHER_CUSTOM_API_PRESET = CUSTOM_API_PRESETS.at(-1)!;
+
+function normalizeBaseUrl(value: string): string {
+ return value.trim().replace(/\/+$/, "").toLowerCase();
+}
+
+/** The preset whose base URL the instance uses, or "Other" for anything else. */
+export function customApiPresetForBaseUrl(baseUrl: string): CustomApiPreset {
+ const normalized = normalizeBaseUrl(baseUrl);
+
+ if (normalized.length === 0) return OTHER_CUSTOM_API_PRESET;
+
+ return (
+ CUSTOM_API_PRESETS.find(
+ (preset) => preset.baseUrl.length > 0 && normalizeBaseUrl(preset.baseUrl) === normalized,
+ ) ?? OTHER_CUSTOM_API_PRESET
+ );
+}
+
+/** Hint shown under the API key field for the given preset. */
+export function customApiKeyHint(preset: CustomApiPreset): string {
+ switch (preset.key.kind) {
+ case "required":
+ return `Required. Create one at ${preset.key.url.replace(/^https:\/\//, "")}.`;
+ case "none":
+ return "Not needed for this server. Leave it empty.";
+ case "optional":
+ return "Leave empty if the endpoint does not need one.";
+ }
+}
+
+export function readCustomApiKey(
+ environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>,
+): ProviderInstanceEnvironmentVariable | undefined {
+ return environment.find((variable) => variable.name === CUSTOM_API_KEY_ENV);
+}
+
+export function withoutCustomApiKey(
+ environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>,
+): ProviderInstanceEnvironmentVariable[] {
+ return environment.filter((variable) => variable.name !== CUSTOM_API_KEY_ENV);
+}
+
+/**
+ * Store the key as a sensitive instance variable so it lives in the secret
+ * store and is redacted from settings. An empty value removes it.
+ */
+export function withCustomApiKey(
+ environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>,
+ value: string,
+): ProviderInstanceEnvironmentVariable[] {
+ const rest = withoutCustomApiKey(environment);
+ const trimmed = value.trim();
+
+ return trimmed.length === 0
+ ? rest
+ : [...rest, { name: CUSTOM_API_KEY_ENV, value: trimmed, sensitive: true }];
+}
+
+/**
+ * Merge edits from the generic environment editor with the stored key. The
+ * key field owns the reserved name, so a generic row with that name is
+ * dropped instead of replacing (and, when empty, deleting) the stored key.
+ */
+export function withStoredCustomApiKey(
+ environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>,
+ stored: ProviderInstanceEnvironmentVariable | undefined,
+): ProviderInstanceEnvironmentVariable[] {
+ const rest = withoutCustomApiKey(environment);
+
+ return stored ? [...rest, stored] : rest;
+}
+
+/** The instance variable that overrides the configured base URL. */
+const CUSTOM_API_BASE_URL_ENV = "CUSTOM_OPENAI_BASE_URL";
+
+/** The parts of a saved instance that decide where its key is sent. */
+export interface CustomApiEndpoint {
+ readonly baseUrl: string;
+ readonly environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>;
+}
+
+function sameVariable(
+ left: ProviderInstanceEnvironmentVariable | undefined,
+ right: ProviderInstanceEnvironmentVariable | undefined,
+): boolean {
+ return (
+ left?.value === right?.value &&
+ left?.sensitive === right?.sensitive &&
+ left?.valueRedacted === right?.valueRedacted
+ );
+}
+
+function urlLeaves(previousBaseUrl: string, nextBaseUrl: string): boolean {
+ const previous = previousBaseUrl.trim();
+ const next = nextBaseUrl.trim();
+
+ if (previous.length === 0) return false;
+
+ if (!URL.canParse(previous) || !URL.canParse(next)) return previous !== next;
+
+ const before = new URL(previous);
+ const after = new URL(next);
+
+ return (
+ before.host !== after.host || (before.protocol === "https:" && after.protocol !== "https:")
+ );
+}
+
+/**
+ * A stored key belongs to the endpoint it was saved for. The driver sends it to
+ * `CUSTOM_OPENAI_BASE_URL` when that variable is set and to the configured base
+ * URL otherwise (the last row wins when the variable repeats), so the key must
+ * go when that address moves to another host or drops from HTTPS to HTTP. A
+ * first URL on an instance that had none keeps the key. A redacted override
+ * cannot be read, so any change to it drops the key, and so does a base URL
+ * move behind it, since a blank override falls back to the base URL.
+ */
+export function customApiKeyLeavesEndpoint(
+ previous: CustomApiEndpoint,
+ next: CustomApiEndpoint,
+): boolean {
+ const override = (endpoint: CustomApiEndpoint) =>
+ endpoint.environment.findLast((variable) => variable.name === CUSTOM_API_BASE_URL_ENV);
+
+ const previousOverride = override(previous);
+ const nextOverride = override(next);
+
+ if (previousOverride?.valueRedacted === true || nextOverride?.valueRedacted === true) {
+ return (
+ !sameVariable(previousOverride, nextOverride) || urlLeaves(previous.baseUrl, next.baseUrl)
+ );
+ }
+
+ const effective = (endpoint: CustomApiEndpoint) =>
+ override(endpoint)?.value.trim() || endpoint.baseUrl;
+
+ return urlLeaves(effective(previous), effective(next));
+}
diff --git a/apps/web/src/components/settings/providerCatalog.ts b/apps/web/src/components/settings/providerCatalog.ts
index f0bd4809a..eb87ff035 100644
--- a/apps/web/src/components/settings/providerCatalog.ts
+++ b/apps/web/src/components/settings/providerCatalog.ts
@@ -1,6 +1,6 @@
import { ProviderDriverKind } from "@akeru/contracts";
-import type { Icon } from "../Icons";
+import { CustomApiIcon, type Icon } from "../Icons";
import {
SUBSCRIPTION_PROVIDERS,
type SubscriptionProviderDefinition,
@@ -46,6 +46,15 @@ export const PROVIDER_CATALOG: ReadonlyArray<ProviderCatalogEntry> = [
subscriptionEntry("grok", "xai", ["grok"]),
subscriptionEntry("kimi-for-coding", "kimi-for-coding", ["kimi"]),
subscriptionEntry("opencode-go", "opencode-go", ["opencodeGo"]),
+ {
+ slug: "custom-api",
+ label: "Custom API",
+ icon: CustomApiIcon,
+ planHint: "OpenAI-compatible endpoint",
+ description: "Bring any OpenAI-compatible API: set a base URL and pick its models.",
+ account: null,
+ drivers: [ProviderDriverKind.make("customOpenai")],
+ },
];
export function providerCatalogEntry(slug: string): ProviderCatalogEntry | undefined {
diff --git a/apps/web/src/components/settings/providerDriverMeta.ts b/apps/web/src/components/settings/providerDriverMeta.ts
index bde09bd12..d528d4686 100644
--- a/apps/web/src/components/settings/providerDriverMeta.ts
+++ b/apps/web/src/components/settings/providerDriverMeta.ts
@@ -1,13 +1,22 @@
import {
ClaudeSettings,
CodexSettings,
+ CustomOpenaiSettings,
GrokSettings,
KimiSettings,
OpenCodeGoSettings,
ProviderDriverKind,
} from "@akeru/contracts";
import type * as Schema from "effect/Schema";
-import { ClaudeAI, GrokIcon, KimiIcon, type Icon, OpenAI, OpenCodeIcon } from "../Icons";
+import {
+ ClaudeAI,
+ CustomApiIcon,
+ GrokIcon,
+ KimiIcon,
+ type Icon,
+ OpenAI,
+ OpenCodeIcon,
+} from "../Icons";
type ProviderSettingsSchema = {
readonly fields: Readonly<Record<string, Schema.Top>>;
@@ -67,6 +76,12 @@ export const PROVIDER_CLIENT_DEFINITIONS: readonly ProviderClientDefinition[] =
icon: OpenCodeIcon,
settingsSchema: OpenCodeGoSettings,
},
+ {
+ value: ProviderDriverKind.make("customOpenai"),
+ label: "Custom API",
+ icon: CustomApiIcon,
+ settingsSchema: CustomOpenaiSettings,
+ },
];
export const PROVIDER_CLIENT_DEFINITION_BY_VALUE: Partial<
diff --git a/apps/web/src/components/settings/providerInstanceCard.logic.ts b/apps/web/src/components/settings/providerInstanceCard.logic.ts
index 4b7e591ac..45ce6f85e 100644
--- a/apps/web/src/components/settings/providerInstanceCard.logic.ts
+++ b/apps/web/src/components/settings/providerInstanceCard.logic.ts
@@ -55,15 +55,22 @@ export function deriveProviderModelsForDisplay(input: {
const serverModels = input.liveModels?.filter((model) => !model.isCustom) ?? [];
- const customModels = input.customModels.map(
- (slug) =>
- liveCustomModelsBySlug.get(slug) ?? {
- slug,
- name: slug,
- isCustom: true,
- capabilities: null,
- },
- );
+ // A hand-added slug the live catalog also reports is one model, not two: a
+ // discovery-capable driver (e.g. Custom API) reports both, and the catalog
+ // row already carries the correct name and capabilities.
+ const serverSlugs = new Set(serverModels.map((model) => model.slug));
+
+ const customModels = input.customModels
+ .filter((slug) => !serverSlugs.has(slug))
+ .map(
+ (slug) =>
+ liveCustomModelsBySlug.get(slug) ?? {
+ slug,
+ name: slug,
+ isCustom: true,
+ capabilities: null,
+ },
+ );
return [...serverModels, ...customModels];
}
diff --git a/apps/web/src/components/settings/providerStatus.test.ts b/apps/web/src/components/settings/providerStatus.test.ts
new file mode 100644
index 000000000..69fd8c241
--- /dev/null
+++ b/apps/web/src/components/settings/providerStatus.test.ts
@@ -0,0 +1,48 @@
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@akeru/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { runtimeConnectionState } from "./providerStatus";
+
+function provider(overrides: Partial<ServerProvider>): ServerProvider {
+ return {
+ instanceId: ProviderInstanceId.make("custom-api"),
+ driver: ProviderDriverKind.make("customOpenai"),
+ enabled: true,
+ installed: true,
+ version: null,
+ status: "ready",
+ auth: { status: "authenticated", type: "apiKey" },
+ checkedAt: "2026-10-02T00:00:00.000Z",
+ availability: "available",
+ models: [],
+ slashCommands: [],
+ skills: [],
+ ...overrides,
+ };
+}
+
+describe("runtimeConnectionState", () => {
+ it("reports an instance that is not set up yet as not connected", () => {
+ const state = runtimeConnectionState(
+ provider({
+ status: "warning",
+ auth: { status: "unauthenticated", type: "apiKey" },
+ message: "Set a base URL in Settings.",
+ }),
+ );
+
+ expect(state).toEqual({
+ tone: "neutral",
+ label: "Not connected",
+ detail: "Set a base URL in Settings.",
+ });
+ });
+
+ it("asks for attention on an error even without a connection", () => {
+ const state = runtimeConnectionState(
+ provider({ status: "error", auth: { status: "unauthenticated", type: "apiKey" } }),
+ );
+
+ expect(state.label).toBe("Needs attention");
+ });
+});
diff --git a/apps/web/src/components/settings/providerStatus.ts b/apps/web/src/components/settings/providerStatus.ts
index ea2a949b9..9ff064fbb 100644
--- a/apps/web/src/components/settings/providerStatus.ts
+++ b/apps/web/src/components/settings/providerStatus.ts
@@ -196,13 +196,18 @@ export function runtimeConnectionState(
return { tone: "positive", label: "Connected", detail: null };
}
- if (provider.status === "error" || provider.status === "warning") {
+ if (provider.status === "error") {
return { tone: "attention", label: "Needs attention", detail: provider.message ?? null };
}
+ // An instance the user has not set up yet is not a problem to fix.
if (provider.auth.status === "unauthenticated") {
return { tone: "neutral", label: "Not connected", detail: provider.message ?? null };
}
+ if (provider.status === "warning") {
+ return { tone: "attention", label: "Needs attention", detail: provider.message ?? null };
+ }
+
return { tone: "positive", label: "Available", detail: null };
}
diff --git a/apps/web/src/lib/contextWindow.ts b/apps/web/src/lib/contextWindow.ts
index f88e543cd..c184ff285 100644
--- a/apps/web/src/lib/contextWindow.ts
+++ b/apps/web/src/lib/contextWindow.ts
@@ -54,6 +54,8 @@ export function formatProviderDisplayName(provider: string | null | undefined):
return "OpenCode";
case "opencodeGo":
return "OpenCode Go";
+ case "customOpenai":
+ return "Custom API";
default: {
// Title-case unknown driver kinds so they read reasonably.
const trimmed = provider.replace(/Agent$/i, "").trim();
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index a6b357601..c2e5ad36e 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -41,6 +41,11 @@ export const PROVIDER_OPTIONS: Array<{
available: true,
pickerSidebarBadge: "new",
},
+ {
+ value: ProviderDriverKind.make("customOpenai"),
+ label: "Custom API",
+ available: true,
+ },
];
export type { PendingApproval, PendingUserInput };
diff --git a/apps/web/src/styles/brand-colors.css b/apps/web/src/styles/brand-colors.css
index 2c8fb3082..8142e8230 100644
--- a/apps/web/src/styles/brand-colors.css
+++ b/apps/web/src/styles/brand-colors.css
@@ -41,4 +41,17 @@
--color-brand-opencode-light-outer: #211e1e;
--color-brand-opencode-dark-inner: #4b4646;
--color-brand-opencode-dark-outer: #f1ecec;
+
+ --color-brand-together-pink: #ef2cc1;
+ --color-brand-together-lilac: #caaef5;
+ --color-brand-together-orange: #fc4c02;
+ --color-brand-deepseek: #4d6bfe;
+ --color-brand-mistral-yellow: #ffd700;
+ --color-brand-mistral-amber: #ffaf00;
+ --color-brand-mistral-orange: #ff8205;
+ --color-brand-mistral-red-orange: #fa500f;
+ --color-brand-mistral-red: #e10500;
+ --color-brand-fireworks: #5019c5;
+ --color-brand-vllm-yellow: #fdb515;
+ --color-brand-vllm-blue: #30a2ff;
}
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
index 00a365632..302dac673 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -7,20 +7,21 @@ orchestration layer does not know which one is behind a thread.
## Built-in drivers
-[`builtInDrivers.ts`][drivers] exports `BUILT_IN_DRIVERS` with six entries:
-
-| Driver kind | Driver source |
-| ------------- | -------------------------------------------- |
-| `codex` | [`Drivers/CodexDriver.ts`][codex] |
-| `claudeAgent` | [`Drivers/ClaudeDriver.ts`][claude] |
-| `grok` | [`Drivers/GrokDriver.ts`][grok] |
-| `kimi` | [`Drivers/KimiDriver.ts`][kimi] |
-| `opencode` | [`Drivers/OpenCodeDriver.ts`][opencode] |
-| `opencodeGo` | [`Drivers/OpenCodeGoDriver.ts`][opencode-go] |
+[`builtInDrivers.ts`][drivers] exports `BUILT_IN_DRIVERS` with seven entries:
+
+| Driver kind | Driver source |
+| -------------- | ------------------------------------------------ |
+| `codex` | [`Drivers/CodexDriver.ts`][codex] |
+| `claudeAgent` | [`Drivers/ClaudeDriver.ts`][claude] |
+| `grok` | [`Drivers/GrokDriver.ts`][grok] |
+| `kimi` | [`Drivers/KimiDriver.ts`][kimi] |
+| `opencode` | [`Drivers/OpenCodeDriver.ts`][opencode] |
+| `opencodeGo` | [`Drivers/OpenCodeGoDriver.ts`][opencode-go] |
+| `customOpenai` | [`Drivers/CustomOpenaiDriver.ts`][custom-openai] |
Each driver declares its `driverKind`, a `configSchema`, and a `create` function that builds a
-provider instance in a child scope. The five subscription drivers supply a Mastra connection;
-standard OpenCode supplies a legacy adapter. Adapter implementations live beside them in
+provider instance in a child scope. The five subscription drivers and Custom API supply a Mastra
+connection; standard OpenCode supplies a legacy adapter. Adapter implementations live beside them in
`apps/server/src/provider/Layers/` (`CodexAdapter.ts`, `ClaudeAdapter.ts`, and so on) and conform to
[`ProviderAdapter.ts`][adapter]. Read the driver plus its adapter to see how a specific agent's
transport, config, and event shapes are mapped.
@@ -39,7 +40,7 @@ Two registries separate configuration from live processes:
directory to route session and turn operations for a thread, so callers name a thread, not an agent.
Desktop chat does not call `ProviderService` directly from orchestration. The command reactor calls
-Akeru's [`AgentController`][controller]. Codex, Claude, Grok, Kimi, and OpenCode Go threads run
+Akeru's [`AgentController`][controller]. Codex, Claude, Grok, Kimi, OpenCode Go, and Custom API threads run
through Akeru's custom Mastra Core controller and call `Session.sendMessage()`. The backing agent is a general-purpose Akeru assistant
with Akeru-owned observational memory, workspace, tools, approval policy, and lifecycle. Akeru builds
workspace and enabled plugin tools per thread, and resolves the selected subscription model through
@@ -153,6 +154,36 @@ revert boundary. OpenCode keeps reverted messages in the transcript until the ne
`readThread` stops at `session.revert.messageID` rather than slicing the local copy. OpenCode Go
stays on Mastra and does not use this adapter path.
+### Custom API
+
+Custom API (`customOpenai`) is not a subscription. Each instance points at one OpenAI-compatible
+endpoint, and Mastra reaches it through the `custom-openai/` model prefix with
+`createOpenAICompatible`. The base URL comes from the instance's `CUSTOM_OPENAI_BASE_URL` variable or
+its `baseUrl` config. The optional key comes only from the instance's sensitive
+`CUSTOM_OPENAI_API_KEY` variable, never from the process environment, so a process-wide key is
+never sent to an arbitrary URL. A base URL alone makes the instance ready, because local servers
+such as Ollama take no key.
+
+The web settings write that key for the user. The add dialog offers presets from
+`apps/web/src/components/settings/customApiPresets.ts` that fill `baseUrl` and the instance name,
+and an **API key** field that saves `CUSTOM_OPENAI_API_KEY` as a sensitive variable. Presets are a
+client convenience: the server stores only the URL, and the card matches the URL back to a preset
+to word its key hint. A key is bound to its endpoint on the client: switching presets in the dialog
+clears the draft key, and a card edit that moves the effective URL (the `CUSTOM_OPENAI_BASE_URL`
+variable when set, `baseUrl` otherwise) to another host, or from HTTPS to HTTP, drops the stored key
+in the same settings update, so the next probe never sends it to the new service. A redacted
+override cannot be read, so any change to it, or a `baseUrl` move behind it, drops the key too. When
+the variable repeats, the last row wins, as it does in the driver. A probe answered with 401 or 403
+reports auth status `unknown`: the card stops showing the instance as connected, but preflight still
+lets turns through, because a scoped key can be refused `/models` and still chat.
+
+The model list is `GET {baseUrl}/models` plus the instance's hand-added models. Discovery is
+optional: a failed or unreadable probe keeps the last good catalog and reports a warning naming only
+the endpoint origin. Disabled instances never probe. The registry drops endpoint models only after a
+probe settles, and never retains a hand-added model the user removed. Until a probe settles, a
+hand-added model the last good catalog also listed keeps its discovered mark, so removing the
+hand-added copy leaves the endpoint's model in place.
+
### Harness-native readiness
Codex, Claude, and Grok use `HarnessProviderStatus.ts`, not their CLI health checks, to publish
@@ -454,6 +485,7 @@ when a request opens (approval) or user input is requested, via
[kimi]: ../../apps/server/src/provider/Drivers/KimiDriver.ts
[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts
[opencode-go]: ../../apps/server/src/provider/Drivers/OpenCodeGoDriver.ts
+[custom-openai]: ../../apps/server/src/provider/Drivers/CustomOpenaiDriver.ts
[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts
diff --git a/docs/user/install.md b/docs/user/install.md
index 648522825..ea2f0baf4 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -84,7 +84,7 @@ the saved connection from the environment.
## What Akeru runs
-Codex, Claude, Grok, Kimi For Coding, and OpenCode Go use Akeru's custom Mastra-based runtime.
+Codex, Claude, Grok, Kimi For Coding, OpenCode Go, and Custom API use Akeru's custom Mastra-based runtime.
Akeru supplies the workspace, memory, plugins, approval rules, and subscription access for each
chat.
diff --git a/docs/user/providers.md b/docs/user/providers.md
index 77750acbe..e261d0070 100644
--- a/docs/user/providers.md
+++ b/docs/user/providers.md
@@ -15,6 +15,36 @@ update. Older models move to the picker's legacy section when a newer one in the
An instance configured with its own credentials uses those credentials rather than the shared
connection. A custom configuration directory alone does not connect an account to Akeru's runtime.
+## Custom API endpoints
+
+**Settings > Providers > Custom API** connects Akeru Bot to any OpenAI-compatible HTTP endpoint: a
+hosted service, a gateway, or a server you run yourself. There is no account to connect and no
+sign-in flow.
+
+When you add a Custom API instance, pick what you are connecting to. OpenRouter, Groq, Together AI,
+DeepSeek, Mistral, Fireworks, LM Studio, Ollama, and vLLM fill in their base URL and a name for you.
+Choose **Other** to type the URL of anything else. Local servers such as LM Studio and Ollama resolve
+on the machine running the environment, not on the device you are using.
+
+Paste the service's key into **API key**. Hosted services need one; local servers usually do not, and
+a base URL alone is enough for them. The key is stored outside the settings file, never sent back to
+a client, and sent to the configured endpoint as a bearer token. On a saved instance the field shows
+that a key is stored. Type a new key to replace it, or use **Remove key**. A key belongs to its
+service: changing the base URL to a different host, or from HTTPS to HTTP, removes the stored key,
+so paste the new service's key afterwards. If the endpoint refuses to list models with that key, the
+instance shows **Needs attention** with the reason until a later check succeeds. You can still chat
+with it, since some keys may use models without listing them.
+
+The model list comes from the endpoint's `/models` response. Models you add by hand are kept alongside
+it, and a model disappears from the picker once the endpoint stops listing it. If Akeru cannot read the
+endpoint, the last successful list stays and the provider row explains what went wrong.
+
+Use **Add instance** on the Custom API page to keep several endpoints side by side, such as a local
+server and a hosted gateway.
+
+The environment sends requests to the URL you configure. Point it only at an endpoint you trust, and
+prefer HTTPS for anything outside your machine.
+
## Subscription login health
After a login or API key save completes, the environment server sends one request that costs nothing, to confirm the account can reach its models or usage endpoint. The check runs on the server, so closing the app or losing the connection right after login does not stop it. While it runs, the provider row shows **Checking health…**. It then changes to **Connected** when the request succeeds or **Failed** when it does not. A failed check does not undo a successful login. Repair the provider account, then use **Reconnect** or **Check OAuth**.
diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.ts
index cfd8ab8f9..4855a1191 100644
--- a/packages/contracts/src/model.ts
+++ b/packages/contracts/src/model.ts
@@ -154,6 +154,8 @@ const OPENCODE_DRIVER_KIND = ProviderDriverKind.make("opencode");
const OPENCODE_GO_DRIVER_KIND = ProviderDriverKind.make("opencodeGo");
+const CUSTOM_OPENAI_DRIVER_KIND = ProviderDriverKind.make("customOpenai");
+
export const DEFAULT_MODEL = "gpt-6.1-sol";
/**
@@ -244,4 +246,5 @@ export const PROVIDER_DISPLAY_NAMES: Partial<Record<ProviderDriverKind, string>>
[KIMI_DRIVER_KIND]: "Kimi For Coding",
[OPENCODE_DRIVER_KIND]: "OpenCode",
[OPENCODE_GO_DRIVER_KIND]: "OpenCode Go",
+ [CUSTOM_OPENAI_DRIVER_KIND]: "Custom API",
};
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 5031103a3..f8f19492b 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -88,6 +88,7 @@ export {
GrokSettings,
KimiSettings,
OpenCodeGoSettings,
+ CustomOpenaiSettings,
OpenCodeSettings,
providerInstanceConfigEnabledFlag,
} from "./settings/providers.ts";
diff --git a/packages/contracts/src/settings/providers.ts b/packages/contracts/src/settings/providers.ts
index 14f545b90..a1a520a59 100644
--- a/packages/contracts/src/settings/providers.ts
+++ b/packages/contracts/src/settings/providers.ts
@@ -185,6 +185,40 @@ export const OpenCodeGoSettings = providerSettingsSchema({
export type OpenCodeGoSettings = typeof OpenCodeGoSettings.Type;
+/**
+ * Any OpenAI-compatible HTTP endpoint: a base URL plus a user-authored model
+ * list. There is no account to sign in to, and no secret here: the API key is
+ * an instance environment variable (`CUSTOM_OPENAI_API_KEY`), because only
+ * sensitive environment variables are kept in the secret store and redacted
+ * before settings reach a client.
+ */
+export const CustomOpenaiSettings = providerSettingsSchema(
+ {
+ enabled: Schema.Boolean.pipe(
+ Schema.withDecodingDefault(Effect.succeed(true)),
+ Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+ ),
+ baseUrl: TrimmedString.pipe(
+ Schema.withDecodingDefault(Effect.succeed("")),
+ Schema.annotateKey({
+ title: "Base URL",
+ description: "The API root of any OpenAI-compatible service.",
+ providerSettingsForm: {
+ placeholder: "https://api.example.com/v1",
+ clearWhenEmpty: "omit",
+ },
+ }),
+ ),
+ customModels: Schema.Array(Schema.String).pipe(
+ Schema.withDecodingDefault(Effect.succeed([])),
+ Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+ ),
+ },
+ { order: ["baseUrl"] },
+);
+
+export type CustomOpenaiSettings = typeof CustomOpenaiSettings.Type;
+
export const OpenCodeSettings = providerSettingsSchema(
{
// Off by default: the binding is not yet stable
@@ -299,6 +333,12 @@ export const OpenCodeGoSettingsPatch = Schema.Struct({
customModels: Schema.optionalKey(Schema.Array(Schema.String)),
});
+export const CustomOpenaiSettingsPatch = Schema.Struct({
+ enabled: Schema.optionalKey(Schema.Boolean),
+ baseUrl: Schema.optionalKey(TrimmedString),
+ customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
export const OpenCodeSettingsPatch = Schema.Struct({
enabled: Schema.optionalKey(Schema.Boolean),
binaryPath: Schema.optionalKey(TrimmedString),
diff --git a/packages/contracts/src/settings/server.ts b/packages/contracts/src/settings/server.ts
index a53581a58..928f41eb8 100644
--- a/packages/contracts/src/settings/server.ts
+++ b/packages/contracts/src/settings/server.ts
@@ -38,12 +38,14 @@ import {
GrokSettings,
KimiSettings,
OpenCodeGoSettings,
+ CustomOpenaiSettings,
OpenCodeSettings,
CodexSettingsPatch,
ClaudeSettingsPatch,
GrokSettingsPatch,
KimiSettingsPatch,
OpenCodeGoSettingsPatch,
+ CustomOpenaiSettingsPatch,
OpenCodeSettingsPatch,
} from "./providers.ts";
import { SandboxSettings, BrowserProviderSettings, SandboxSettingsPatch } from "./sandbox.ts";
@@ -228,6 +230,7 @@ export const ServerSettings = Schema.Struct({
kimi: KimiSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
opencode: OpenCodeSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
opencodeGo: OpenCodeGoSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+ customOpenai: CustomOpenaiSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
}).pipe(Schema.withDecodingDefault(Effect.succeed({}))),
// New driver-agnostic instance map. Keyed by `ProviderInstanceId`; values
// are `ProviderInstanceConfig` envelopes. The driver-specific config blob
@@ -366,6 +369,7 @@ const ServerSettingsPatchFields = {
kimi: Schema.optionalKey(KimiSettingsPatch),
opencode: Schema.optionalKey(OpenCodeSettingsPatch),
opencodeGo: Schema.optionalKey(OpenCodeGoSettingsPatch),
+ customOpenai: Schema.optionalKey(CustomOpenaiSettingsPatch),
}),
),
// Whole-map replacement for the new instance config. Patching individual
diff --git a/packages/shared/src/delegationProviders.ts b/packages/shared/src/delegationProviders.ts
index 5a18f344f..57e806ae8 100644
--- a/packages/shared/src/delegationProviders.ts
+++ b/packages/shared/src/delegationProviders.ts
@@ -10,6 +10,7 @@ export const DELEGATION_DRIVER_KINDS = [
"grok",
"kimi",
"opencodeGo",
+ "customOpenai",
] as const;
const delegationDriverKinds: ReadonlySet<string> = new Set(DELEGATION_DRIVER_KINDS);