Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

add custom AI providers in config (#7771)

Shahmir Varqha093b8a780d15
diff --git a/docs/_static/docs-add-custom-provider.mp4 b/docs/_static/docs-add-custom-provider.mp4
new file mode 100644
index 0000000000..5d4d21bb57
Binary files /dev/null and b/docs/_static/docs-add-custom-provider.mp4 differ
diff --git a/docs/guides/configuration/llm_providers.md b/docs/guides/configuration/llm_providers.md
index fe33cefa2b..9ccdcbfa07 100644
--- a/docs/guides/configuration/llm_providers.md
+++ b/docs/guides/configuration/llm_providers.md
@@ -211,13 +211,14 @@ The deployment name is typically the model name.
**Azure AI Foundry**
-AI Foundry uses OpenAI-compatible models, so you can use the same configuration as OpenAI-compatible providers.
+AI Foundry uses OpenAI-compatible models. You can configure it as a custom provider:
```toml title="marimo.toml"
[ai.models]
-custom_models = ["custom-azure/mistral-medium"]
+custom_models = ["azure_foundry/mistral-medium"]
+chat_model = "azure_foundry/mistral-medium"
-[ai.open_ai_compatible]
+[ai.custom_providers.azure_foundry]
api_key = "sk-proj-..."
base_url = "https://<your-resource-name>.services.ai.azure.com/openai/v1"
```
@@ -365,10 +366,9 @@ autocomplete_model = "ollama/codellama" # or another model from `ollama ls`
curl http://127.0.0.1:11434/v1/models
```
-### OpenAI-compatible providers
+## Custom providers
-Many providers expose OpenAI-compatible endpoints. Point `base_url` at the provider and use their models.
-Common examples include [GROQ](https://console.groq.com/docs/openai), DeepSeek, xAI, Together AI, and LM Studio.
+Add multiple OpenAI-compatible providers through the Settings UI. Each custom provider gets its own configuration section and can be referenced by name in your model settings. The following section is a <strong>non-exhaustive</strong> list of supported providers.
**Requirements**
@@ -376,42 +376,43 @@ Common examples include [GROQ](https://console.groq.com/docs/openai), DeepSeek,
* Provider OpenAI-compatible `base_url`
* `pip install openai` or `uv add openai`
-**Configuration**
-
-```toml title="marimo.toml"
-[ai.models]
-chat_model = "provider-x/some-model"
+**Adding a custom provider via UI (recommended)**
-[ai.open_ai_compatible]
-api_key = "..."
-base_url = "https://api.provider-x.com/"
-```
+1. Open marimo's Settings panel
+2. Navigate to **AI** → **AI Providers**
+3. Scroll to **Custom Providers** and click **Add Provider**
+4. Navigate to the **AI Models** tab and select your custom provider.
-??? tip "Use the `/v1` path if required by your provider"
- Some OpenAI-compatible providers expose their API under `/v1` (e.g., `https://host/v1`). If you see 404s, add `/v1` to your `base_url`.
+<div align="center">
+<video autoplay muted loop playsinline width="640px" height="480px">
+ <source src="/_static/docs-add-custom-provider.mp4" type="video/mp4">
+ Your browser does not support the video tag.
+</video>
+</div>
-??? tip "Using OpenAI-compatible providers"
+**Configuration via marimo.toml**
- === "Via UI Settings"
+You can also configure custom providers directly in `marimo.toml`:
- 1. Open marimo's Settings panel
- 2. Navigate to the AI section
- 3. Enter your provider's API key in the "OpenAI-Compatible" section
- 4. Set Base URL to your provider (e.g., `https://api.provider-x.com`)
- 5. Set Model to your provider's model slug
+```toml title="marimo.toml"
+[ai.models]
+chat_model = "groq/llama-3.1-70b-versatile"
+edit_model = "together/meta-llama/Llama-3-70b-chat-hf"
- === "Via marimo.toml"
+[ai.custom_providers.groq]
+api_key = "gsk-..."
+base_url = "https://api.groq.com/openai/v1"
- Add this to `marimo.toml`:
+[ai.custom_providers.together]
+api_key = "tg-..."
+base_url = "https://api.together.xyz/v1"
- ```toml
- [ai.models]
- chat_model = "provider-x/some-model"
+[ai.custom_providers.my_local_server]
+base_url = "http://localhost:8000/v1"
+```
- [ai.open_ai_compatible]
- api_key = "px-..."
- base_url = "https://api.provider-x.com/"
- ```
+??? tip "Use the `/v1` path if required by your provider"
+ Some OpenAI-compatible providers expose their API under `/v1` (e.g., `https://host/v1`). If you see 404s, add `/v1` to your `base_url`.
### DeepSeek
@@ -420,7 +421,6 @@ Use DeepSeek via its OpenAI‑compatible API.
**Requirements**
* DeepSeek API key
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -428,7 +428,7 @@ Use DeepSeek via its OpenAI‑compatible API.
[ai.models]
chat_model = "deepseek/deepseek-chat" # or "deepseek-reasoner"
-[ai.open_ai_compatible]
+[ai.custom_providers.deepseek]
api_key = "dsk-..."
base_url = "https://api.deepseek.com/"
```
@@ -440,7 +440,6 @@ Use Grok models via xAI's OpenAI‑compatible API.
**Requirements**
* xAI API key
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -448,7 +447,7 @@ Use Grok models via xAI's OpenAI‑compatible API.
[ai.models]
chat_model = "xai/grok-2-latest"
-[ai.open_ai_compatible]
+[ai.custom_providers.xai]
api_key = "xai-..."
base_url = "https://api.x.ai/v1/"
```
@@ -460,7 +459,6 @@ Connect to a local model served by LM Studio's OpenAI‑compatible endpoint.
**Requirements**
* Install LM Studio and start its server
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -468,7 +466,7 @@ Connect to a local model served by LM Studio's OpenAI‑compatible endpoint.
[ai.models]
chat_model = "lmstudio/qwen2.5-coder-7b"
-[ai.open_ai_compatible]
+[ai.custom_providers.lmstudio]
base_url = "http://127.0.0.1:1234/v1" # LM Studio server
```
@@ -479,7 +477,6 @@ Use Mistral via its OpenAI‑compatible API.
**Requirements**
* Mistral API key
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -487,7 +484,7 @@ Use Mistral via its OpenAI‑compatible API.
[ai.models]
chat_model = "mistral/mistral-small-latest" # e.g., codestral-latest, mistral-large-latest
-[ai.open_ai_compatible]
+[ai.custom_providers.mistral]
api_key = "mistral-..."
base_url = "https://api.mistral.ai/v1/"
```
@@ -499,7 +496,6 @@ Access multiple hosted models via Together AI's OpenAI‑compatible API.
**Requirements**
* Together AI API key
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -507,7 +503,7 @@ Access multiple hosted models via Together AI's OpenAI‑compatible API.
[ai.models]
chat_model = "together/mistralai/Mixtral-8x7B-Instruct-v0.1"
-[ai.open_ai_compatible]
+[ai.custom_providers.together]
api_key = "tg-..."
base_url = "https://api.together.xyz/v1/"
```
@@ -519,7 +515,6 @@ Use Vercel's v0 OpenAI‑compatible models for app-oriented generation.
**Requirements**
* v0 API key
-* `pip install openai` or `uv add openai`
**Configuration**
@@ -527,10 +522,29 @@ Use Vercel's v0 OpenAI‑compatible models for app-oriented generation.
[ai.models]
chat_model = "v0/v0-1.5-md"
-[ai.open_ai_compatible]
+[ai.custom_providers.v0]
api_key = "v0-..."
base_url = "https://api.v0.dev/" # Verify the endpoint in v0 docs
```
See the [LiteLLM provider list](https://litellm.vercel.app/docs/providers) for more options. For non‑compatible APIs, submit a
[feature request](https://github.com/marimo-team/marimo/issues/new?template=feature_request.yaml).
+
+
+### OpenAI-compatible (legacy)
+
+!!! note "Prefer custom providers"
+ The `[ai.open_ai_compatible]` section is still supported for backward compatibility, but we recommend using **custom providers** instead, which allows you to configure multiple providers with distinct names.
+
+For a single OpenAI-compatible provider, you can use:
+
+```toml title="marimo.toml"
+[ai.models]
+chat_model = "provider-x/some-model"
+
+[ai.open_ai_compatible]
+api_key = "..."
+base_url = "https://api.provider-x.com/"
+```
+
+Models that don't match a known provider prefix will fall back to this configuration.
diff --git a/frontend/src/components/app-config/ai-config.tsx b/frontend/src/components/app-config/ai-config.tsx
index e1181ab3e4..4bbb25d362 100644
--- a/frontend/src/components/app-config/ai-config.tsx
+++ b/frontend/src/components/app-config/ai-config.tsx
@@ -34,7 +34,8 @@ import { Textarea } from "@/components/ui/textarea";
import type { SupportedRole } from "@/core/ai/config";
import {
AiModelId,
- PROVIDERS,
+ KNOWN_PROVIDERS,
+ type KnownProviderId,
type ProviderId,
type QualifiedModelId,
type ShortModelId,
@@ -90,6 +91,11 @@ interface AiProviderTitleProps {
children: React.ReactNode;
}
+interface CustomProviderConfig {
+ api_key?: string;
+ base_url?: string;
+}
+
export const AiProviderTitle: React.FC<AiProviderTitleProps> = ({
provider,
children,
@@ -555,15 +561,18 @@ const AccordionFormItem = ({
provider,
children,
isConfigured,
+ value,
}: {
title: string;
triggerClassName?: string;
provider: AiProviderIconProps["provider"];
children: React.ReactNode;
isConfigured: boolean;
+ /** Custom value for the accordion item. Defaults to provider. */
+ value?: string;
}) => {
return (
- <AccordionItem value={provider}>
+ <AccordionItem value={value ?? provider}>
<AccordionTrigger className={triggerClassName}>
<AiProviderTitle provider={provider}>
{title}
@@ -581,9 +590,228 @@ const AccordionFormItem = ({
);
};
+export const CustomProvidersConfig: React.FC<AiConfigProps> = ({
+ form,
+ config,
+ onSubmit,
+}) => {
+ const [isAddingProvider, setIsAddingProvider] = useState(false);
+ const [newProviderName, setNewProviderName] = useState("");
+ const [newProviderApiKey, setNewProviderApiKey] = useState("");
+ const [newProviderBaseUrl, setNewProviderBaseUrl] = useState("");
+
+ const providerNameInputId = useId();
+ const apiKeyInputId = useId();
+ const baseUrlInputId = useId();
+
+ const normalizedName = newProviderName.toLowerCase().replaceAll(/\s+/g, "_");
+ const customProviders = form.watch("ai.custom_providers");
+ const isDuplicate =
+ KNOWN_PROVIDERS.includes(normalizedName as KnownProviderId) ||
+ (customProviders && Object.keys(customProviders).includes(normalizedName));
+
+ const hasValidValues =
+ normalizedName.trim() && newProviderBaseUrl.trim() && !isDuplicate;
+
+ const resetForm = () => {
+ setNewProviderName("");
+ setNewProviderApiKey("");
+ setNewProviderBaseUrl("");
+ setIsAddingProvider(false);
+ };
+
+ return (
+ <FormField
+ control={form.control}
+ name="ai.custom_providers"
+ render={({ field }) => {
+ const customProviders = (field.value || {}) as Record<
+ string,
+ CustomProviderConfig
+ >;
+ const customProviderEntries = Object.entries(customProviders);
+
+ const addProvider = () => {
+ if (!hasValidValues) {
+ return;
+ }
+ field.onChange({
+ ...customProviders,
+ [normalizedName]: {
+ api_key: newProviderApiKey || undefined,
+ base_url: newProviderBaseUrl,
+ },
+ });
+ onSubmit(form.getValues());
+ resetForm();
+ };
+
+ const removeProvider = (providerName: string) => {
+ const { [providerName]: _, ...rest } = customProviders;
+ // Reset to clear nested dirty state, then set new value
+ form.resetField("ai.custom_providers");
+ form.setValue("ai.custom_providers", rest, { shouldDirty: true });
+ onSubmit(form.getValues());
+ };
+
+ const providerForm = (
+ <div className="flex flex-col gap-3 p-4 border border-border rounded-md bg-muted/20">
+ <div className="flex flex-col gap-1.5">
+ <Label htmlFor={providerNameInputId}>Provider Name</Label>
+ <Input
+ id={providerNameInputId}
+ placeholder="e.g., together, groq, mistral"
+ value={newProviderName}
+ onChange={(e) => setNewProviderName(e.target.value)}
+ />
+ {isDuplicate && (
+ <p className="text-xs text-destructive">
+ A provider with this name already exists.
+ </p>
+ )}
+ {newProviderName && (
+ <p className="text-xs text-muted-secondary">
+ Use models with prefix:{" "}
+ <Kbd className="inline text-xs">{normalizedName}/</Kbd>
+ </p>
+ )}
+ </div>
+
+ <div className="flex flex-col gap-1.5">
+ <Label htmlFor={baseUrlInputId}>
+ Base URL <span className="text-destructive">*</span>
+ </Label>
+ <Input
+ id={baseUrlInputId}
+ placeholder="e.g., https://api.together.xyz/v1"
+ value={newProviderBaseUrl}
+ onChange={(e) => setNewProviderBaseUrl(e.target.value)}
+ />
+ </div>
+
+ <div className="flex flex-col gap-1.5">
+ <Label htmlFor={apiKeyInputId}>API Key (optional)</Label>
+ <Input
+ id={apiKeyInputId}
+ placeholder="sk-..."
+ type="password"
+ value={newProviderApiKey}
+ onChange={(e) => setNewProviderApiKey(e.target.value)}
+ />
+ </div>
+
+ <div className="flex gap-2 mt-1">
+ <Button
+ onClick={addProvider}
+ disabled={!hasValidValues}
+ size="xs"
+ >
+ Add Provider
+ </Button>
+ <Button variant="outline" onClick={resetForm} size="xs">
+ Cancel
+ </Button>
+ </div>
+ </div>
+ );
+
+ const renderAccordionItem = ({
+ providerName,
+ providerConfig,
+ onRemove,
+ }: {
+ providerName: string;
+ providerConfig: CustomProviderConfig;
+ onRemove: (name: string) => void;
+ }) => {
+ const displayName = Strings.startCase(providerName);
+ const isConfigured =
+ !!providerConfig.api_key || !!providerConfig.base_url;
+
+ return (
+ <AccordionFormItem
+ key={`custom-${providerName}`}
+ title={displayName}
+ provider={providerName}
+ value={`custom-${providerName}`}
+ isConfigured={isConfigured}
+ >
+ <ApiKey
+ form={form}
+ config={config}
+ name={
+ `ai.custom_providers.${providerName}.api_key` as FieldPath<UserConfig>
+ }
+ placeholder="sk-..."
+ testId={`custom-provider-${providerName}-api-key`}
+ />
+ <BaseUrl
+ form={form}
+ config={config}
+ name={
+ `ai.custom_providers.${providerName}.base_url` as FieldPath<UserConfig>
+ }
+ placeholder="https://api.example.com/v1"
+ testId={`custom-provider-${providerName}-base-url`}
+ />
+ <Button
+ variant="destructive"
+ size="xs"
+ onClick={(e) => {
+ e.stopPropagation();
+ e.preventDefault();
+ onRemove(providerName);
+ }}
+ className="w-fit self-end"
+ >
+ <Trash2Icon className="h-4 w-4 mr-2" />
+ Remove Provider
+ </Button>
+ </AccordionFormItem>
+ );
+ };
+
+ return (
+ <SettingGroup>
+ <SettingSubtitle>Custom Providers</SettingSubtitle>
+ <p className="text-sm text-muted-secondary">
+ Add your own OpenAI-compatible provider. Once added, you can
+ configure models in the AI Models tab.
+ </p>
+
+ {customProviderEntries.length > 0 && (
+ <Accordion type="multiple" className="-mt-4">
+ {customProviderEntries.map(([name, providerConfig]) =>
+ renderAccordionItem({
+ providerName: name,
+ providerConfig,
+ onRemove: removeProvider,
+ }),
+ )}
+ </Accordion>
+ )}
+
+ {isAddingProvider ? (
+ providerForm
+ ) : (
+ <AddButton
+ className="self-start"
+ isFormOpen={isAddingProvider}
+ setIsFormOpen={setIsAddingProvider}
+ label="Add Provider"
+ />
+ )}
+ </SettingGroup>
+ );
+ }}
+ />
+ );
+};
+
export const AiProvidersConfig: React.FC<AiConfigProps> = ({
form,
config,
+ onSubmit,
}) => {
const isWasmRuntime = isWasm();
@@ -903,13 +1131,17 @@ export const AiProvidersConfig: React.FC<AiConfigProps> = ({
</AccordionFormItem>
<AccordionFormItem
- title="OpenAI-Compatible"
+ title="OpenAI-Compatible (Legacy)"
provider="openai-compatible"
isConfigured={
hasValue("ai.open_ai_compatible.api_key") &&
hasValue("ai.open_ai_compatible.base_url")
}
>
+ <p className="text-sm text-amber-600 dark:text-amber-400 mb-2">
+ Consider using Custom Providers instead, which allows you to add
+ multiple providers with distinct names.
+ </p>
<ApiKey
form={form}
config={config}
@@ -933,6 +1165,8 @@ export const AiProvidersConfig: React.FC<AiConfigProps> = ({
/>
</AccordionFormItem>
</Accordion>
+
+ <CustomProvidersConfig form={form} config={config} onSubmit={onSubmit} />
</SettingGroup>
);
};
@@ -1133,6 +1367,16 @@ export const AiModelDisplayConfig: React.FC<AiConfigProps> = ({
name: "ai.models.custom_models",
}) as QualifiedModelId[];
+ const customProviders = useWatch({
+ control: form.control,
+ name: "ai.custom_providers",
+ }) as Record<string, CustomProviderConfig> | undefined;
+
+ const customProviderNames = useMemo(
+ () => Object.keys(customProviders || {}),
+ [customProviders],
+ );
+
const aiModelRegistry = useMemo(
() =>
AiModelRegistry.create({
@@ -1212,6 +1456,7 @@ export const AiModelDisplayConfig: React.FC<AiConfigProps> = ({
<AddModelForm
form={form}
customModels={customModels}
+ customProviderNames={customProviderNames}
onSubmit={onSubmit}
/>
</SettingGroup>
@@ -1221,8 +1466,9 @@ export const AiModelDisplayConfig: React.FC<AiConfigProps> = ({
export const AddModelForm: React.FC<{
form: UseFormReturn<UserConfig>;
customModels: QualifiedModelId[];
+ customProviderNames: string[];
onSubmit: (values: UserConfig) => void;
-}> = ({ form, customModels, onSubmit }) => {
+}> = ({ form, customModels, customProviderNames, onSubmit }) => {
const [isFormOpen, setIsFormOpen] = useState(false);
const [modelAdded, setModelAdded] = useState(false);
const [provider, setProvider] = useState<ProviderId | "custom" | null>(null);
@@ -1293,23 +1539,46 @@ export const AddModelForm: React.FC<{
</SelectTrigger>
<SelectContent>
<SelectGroup>
+ {customProviderNames.length > 0 && (
+ <>
+ <p className="px-2 py-1 text-xs text-muted-secondary font-medium">
+ Custom Providers
+ </p>
+ {customProviderNames.map((p) => (
+ <SelectItem key={p} value={p}>
+ <div className="flex items-center gap-2">
+ <AiProviderIcon provider={p} className="h-4 w-4" />
+ <span>{Strings.startCase(p)}</span>
+ </div>
+ </SelectItem>
+ ))}
+ <p className="px-2 py-1 text-xs text-muted-secondary font-medium mt-1">
+ Built-in Providers
+ </p>
+ </>
+ )}
+ {KNOWN_PROVIDERS.filter(
+ (p) => p !== "marimo" && !customProviderNames.includes(p),
+ ).map((p) => (
+ <SelectItem key={p} value={p}>
+ <div className="flex items-center gap-2">
+ <AiProviderIcon provider={p} className="h-4 w-4" />
+ <span>{getProviderLabel(p)}</span>
+ </div>
+ </SelectItem>
+ ))}
+ <p className="px-2 py-1 text-xs text-muted-secondary font-medium mt-1">
+ Other
+ </p>
<SelectItem value="custom">
<div className="flex items-center gap-2">
<AiProviderIcon
provider="openai-compatible"
className="h-4 w-4"
/>
- <span>Custom</span>
+ <span>Enter provider name</span>
</div>
</SelectItem>
- {PROVIDERS.filter((p) => p !== "marimo").map((p) => (
- <SelectItem key={p} value={p}>
- <div className="flex items-center gap-2">
- <AiProviderIcon provider={p} className="h-4 w-4" />
- <span>{getProviderLabel(p)}</span>
- </div>
- </SelectItem>
- ))}
</SelectGroup>
</SelectContent>
</Select>
@@ -1379,17 +1648,12 @@ export const AddModelForm: React.FC<{
<div>
{isFormOpen && inputForm}
<div className="flex flex-row text-sm">
- <Button
- onClick={(e) => {
- e.preventDefault();
- setIsFormOpen(true);
- }}
- variant="link"
- disabled={isFormOpen}
- >
- <PlusIcon className="h-4 w-4 mr-2 mb-0.5" />
- Add Model
- </Button>
+ <AddButton
+ isFormOpen={isFormOpen}
+ setIsFormOpen={setIsFormOpen}
+ label="Add Model"
+ className="pl-2"
+ />
{modelAdded && (
<div className="flex items-center gap-1 text-green-700 bg-green-500/10 px-2 py-1 rounded-md ml-auto">
✓ Model added
@@ -1400,6 +1664,34 @@ export const AddModelForm: React.FC<{
);
};
+const AddButton = ({
+ isFormOpen,
+ setIsFormOpen,
+ label,
+ className,
+}: {
+ isFormOpen: boolean;
+ setIsFormOpen: (isOpen: boolean) => void;
+ label: string;
+ className?: string;
+}) => {
+ return (
+ <Button
+ onClick={(e) => {
+ e.stopPropagation();
+ e.preventDefault();
+ setIsFormOpen(true);
+ }}
+ variant="link"
+ disabled={isFormOpen}
+ className={cn("px-0", className)}
+ >
+ <PlusIcon className="h-4 w-4 mr-2 mb-0.5" />
+ {label}
+ </Button>
+ );
+};
+
export const AiConfig: React.FC<AiConfigProps> = ({
form,
config,
diff --git a/frontend/src/components/app-config/user-config-form.tsx b/frontend/src/components/app-config/user-config-form.tsx
index 5cd3d1e7cd..d164fb7e08 100644
--- a/frontend/src/components/app-config/user-config-form.tsx
+++ b/frontend/src/components/app-config/user-config-form.tsx
@@ -71,12 +71,19 @@ export function getDirtyValues<T extends FieldValues>(
const result: Partial<T> = {};
for (const key of Object.keys(dirtyFields) as (keyof T)[]) {
const dirty = dirtyFields[key];
+ const value = values[key];
+
+ // Skip if the value no longer exists (e.g., deleted from a record)
+ if (value === undefined) {
+ continue;
+ }
+
if (dirty === true) {
- result[key] = values[key];
+ result[key] = value;
} else if (typeof dirty === "object" && dirty !== null) {
// Nested object - recurse
const nested = getDirtyValues(
- values[key] as FieldValues,
+ value as FieldValues,
dirty as Partial<Record<string, unknown>>,
);
if (Object.keys(nested).length > 0) {
diff --git a/frontend/src/core/ai/ids/ids.ts b/frontend/src/core/ai/ids/ids.ts
index 6b221142c0..16617dc88b 100644
--- a/frontend/src/core/ai/ids/ids.ts
+++ b/frontend/src/core/ai/ids/ids.ts
@@ -2,7 +2,7 @@
import type { TypedString } from "@/utils/typed";
-export const PROVIDERS = [
+export const KNOWN_PROVIDERS = [
"openai",
"anthropic",
"google",
@@ -15,7 +15,13 @@ export const PROVIDERS = [
"wandb",
"marimo",
] as const;
-export type ProviderId = (typeof PROVIDERS)[number];
+export type KnownProviderId = (typeof KNOWN_PROVIDERS)[number];
+
+/**
+ * Provider ID can be a known provider or a custom string
+ * The (string & {}) pattern allows any string while still providing autocomplete for known providers
+ */
+export type ProviderId = KnownProviderId | (string & {});
export type ShortModelId = TypedString<"ShortModelId">;
@@ -68,6 +74,8 @@ function guessProviderId(id: string): ProviderId {
return "ollama";
}
-export function isKnownAIProvider(providerId: ProviderId): boolean {
- return PROVIDERS.includes(providerId);
+export function isKnownAIProvider(
+ providerId: string,
+): providerId is KnownProviderId {
+ return (KNOWN_PROVIDERS as readonly string[]).includes(providerId);
}
diff --git a/frontend/src/core/config/__tests__/config-schema.test.ts b/frontend/src/core/config/__tests__/config-schema.test.ts
index 80040e1a34..3109bd4a0a 100644
--- a/frontend/src/core/config/__tests__/config-schema.test.ts
+++ b/frontend/src/core/config/__tests__/config-schema.test.ts
@@ -45,6 +45,7 @@ test("default UserConfig - empty", () => {
expect(defaultConfig).toMatchInlineSnapshot(`
{
"ai": {
+ "custom_providers": {},
"inline_tooltip": false,
"mode": "manual",
"models": {
@@ -114,6 +115,7 @@ test("default UserConfig - one level", () => {
expect(defaultConfig).toMatchInlineSnapshot(`
{
"ai": {
+ "custom_providers": {},
"inline_tooltip": false,
"mode": "manual",
"models": {
@@ -198,6 +200,40 @@ test("default UserConfig with additional information", () => {
);
});
+test("UserConfig with custom_providers", () => {
+ const config = UserConfigSchema.parse({
+ ai: {
+ custom_providers: {
+ my_provider: {
+ api_key: "test-key",
+ base_url: "https://api.example.com/v1",
+ },
+ another_provider: {
+ base_url: "https://api.another.com/v1",
+ },
+ },
+ },
+ });
+
+ expect(config.ai?.custom_providers).toEqual({
+ my_provider: {
+ api_key: "test-key",
+ base_url: "https://api.example.com/v1",
+ },
+ another_provider: {
+ base_url: "https://api.another.com/v1",
+ },
+ });
+});
+
+test("UserConfig custom_providers defaults to empty object", () => {
+ const config = UserConfigSchema.parse({
+ ai: {},
+ });
+
+ expect(config.ai?.custom_providers).toEqual({});
+});
+
test("resolvedMarimoConfigAtom overrides correctly and does not mutate the original array", () => {
const initialUserConfig = {
completion: {
diff --git a/frontend/src/core/config/config-schema.ts b/frontend/src/core/config/config-schema.ts
index 2186c1a2c8..1383086081 100644
--- a/frontend/src/core/config/config-schema.ts
+++ b/frontend/src/core/config/config-schema.ts
@@ -175,6 +175,7 @@ export const UserConfigSchema = z
aws_secret_access_key: z.string().optional(),
})
.optional(),
+ custom_providers: z.record(z.string(), AiConfigSchema).prefault({}),
models: AiModelsSchema.prefault({
displayed_models: [],
custom_models: [],
diff --git a/marimo/_config/config.py b/marimo/_config/config.py
index b85804a804..c87f4fae46 100644
--- a/marimo/_config/config.py
+++ b/marimo/_config/config.py
@@ -298,7 +298,8 @@ class AiConfig(TypedDict, total=False):
- `github`: the GitHub config
- `openrouter`: the OpenRouter config
- `wandb`: the Weights & Biases config
- - `open_ai_compatible`: the OpenAI-compatible config
+ - `custom_providers`: a dict of custom OpenAI-compatible providers
+ - `open_ai_compatible`: the OpenAI-compatible config (deprecated, use custom_providers)
"""
rules: NotRequired[str]
@@ -317,6 +318,8 @@ class AiConfig(TypedDict, total=False):
github: GitHubConfig
openrouter: OpenAiConfig
wandb: OpenAiConfig
+ custom_providers: NotRequired[dict[str, OpenAiConfig]]
+ # @deprecated: use `custom_providers` instead
open_ai_compatible: OpenAiConfig
@@ -705,7 +708,8 @@ DEFAULT_CONFIG: MarimoConfig = {
"models": {
"displayed_models": [],
"custom_models": [],
- }
+ },
+ "custom_providers": {},
},
"snippets": {
"custom_paths": [],
@@ -748,10 +752,17 @@ def merge_config(
config = deep_copy(config)
config.get("keymap", {}).pop("overrides", {})
+ # Fields that should be replaced instead of merged.
+ # These are "record" types where keys can be added/removed,
+ # as opposed to config objects where you only set specific fields.
+ replace_paths = frozenset({"ai.custom_providers"})
+
merged = cast(
MarimoConfig,
deep_merge(
- cast(dict[Any, Any], config), cast(dict[Any, Any], new_config)
+ cast(dict[Any, Any], config),
+ cast(dict[Any, Any], new_config),
+ replace_paths=replace_paths,
),
)
diff --git a/marimo/_config/secrets.py b/marimo/_config/secrets.py
index 1bf4735ae9..e104025940 100644
--- a/marimo/_config/secrets.py
+++ b/marimo/_config/secrets.py
@@ -45,6 +45,7 @@ def mask_secrets(config: MarimoConfig) -> MarimoConfig:
secrets = (
("ai", "*", "api_key"),
+ ("ai", "custom_providers", "*", "api_key"),
("ai", "bedrock", "aws_access_key_id"),
("ai", "bedrock", "aws_secret_access_key"),
("runtime", "dotenv"),
diff --git a/marimo/_server/ai/config.py b/marimo/_server/ai/config.py
index 5686b36b04..3eeb797460 100644
--- a/marimo/_server/ai/config.py
+++ b/marimo/_server/ai/config.py
@@ -72,6 +72,30 @@ class AnyProviderConfig:
config, "open_ai_compatible", "OpenAI Compatible"
)
+ @classmethod
+ def for_custom_provider(
+ cls, config: AiConfig, provider_name: str
+ ) -> AnyProviderConfig:
+ """Get config for a custom provider by name."""
+ custom_providers = cast(
+ dict[str, Any], config.get("custom_providers", {})
+ )
+ if provider_name not in custom_providers:
+ raise HTTPException(
+ status_code=HTTPStatus.BAD_REQUEST,
+ detail=f"Custom provider '{provider_name}' not configured. "
+ "Go to Settings > AI to configure.",
+ )
+
+ provider_config = cast(dict[str, Any], custom_providers[provider_name])
+ return cls._for_openai_like(
+ config,
+ key=provider_name,
+ name=provider_name.replace("_", " ").title(),
+ require_key=False,
+ ai_config=provider_config,
+ )
+
@classmethod
def for_ollama(cls, config: AiConfig) -> AnyProviderConfig:
default_base_url = "http://127.0.0.1:11434/v1"
@@ -147,8 +171,9 @@ class AnyProviderConfig:
fallback_key: Optional[str] = None,
fallback_base_url: Optional[str] = None,
require_key: bool = False,
+ ai_config: dict[str, Any] | None = None,
) -> AnyProviderConfig:
- ai_config: dict[str, Any] = _get_ai_config(config, key)
+ ai_config = ai_config or _get_ai_config(config, key)
key = _get_key(
ai_config, name, fallback_key=fallback_key, require_key=require_key
)
@@ -240,6 +265,12 @@ class AnyProviderConfig:
elif model_id.provider == "openai_compatible":
return cls.for_openai_compatible(config)
else:
+ custom_providers = cast(
+ dict[str, Any], config.get("custom_providers", {})
+ )
+ if model_id.provider in custom_providers:
+ return cls.for_custom_provider(config, model_id.provider)
+
# Catch-all: try OpenAI compatible first, then OpenAI.
try:
if "open_ai_compatible" in config:
diff --git a/marimo/_utils/deep_merge.py b/marimo/_utils/deep_merge.py
index 278fedc993..e90380a7ec 100644
--- a/marimo/_utils/deep_merge.py
+++ b/marimo/_utils/deep_merge.py
@@ -5,18 +5,29 @@ from typing import Any
def _merge_key(
- original: dict[Any, Any], update: dict[Any, Any], key: str
+ original: dict[Any, Any],
+ update: dict[Any, Any],
+ key: str,
+ replace_paths: frozenset[str],
+ current_path: str,
) -> Any:
# Precondition: key is in at least one of original and update
+ path = f"{current_path}.{key}" if current_path else key
+
if key not in update:
# keep keys in original if they aren't in the update
return original[key]
elif key not in original:
# new keys in update get added to original
return update[key]
+ elif path in replace_paths:
+ # This path should be replaced, not merged
+ return update[key]
elif isinstance(original[key], dict) and isinstance(update[key], dict):
# both dicts, so recurse
- return deep_merge(original[key], update[key])
+ return deep_merge(
+ original[key], update[key], replace_paths, current_path=path
+ )
else:
# key is present in both original and update, but values are not
# both dicts; just take the update value.
@@ -24,10 +35,31 @@ def _merge_key(
def deep_merge(
- original: dict[Any, Any], update: dict[Any, Any]
+ original: dict[Any, Any],
+ update: dict[Any, Any],
+ replace_paths: frozenset[str] | None = None,
+ current_path: str = "",
) -> dict[Any, Any]:
- """Deep merge of two dicts."""
+ """Deep merge of two dicts.
+
+ Args:
+ original: The original dict.
+ update: The dict to merge into the original.
+ replace_paths: Optional set of dot-separated paths that should be
+ replaced instead of merged. For example, {"ai.custom_providers"}
+ means that if both original and update have ai.custom_providers,
+ the update value will completely replace the original instead of
+ being deep merged.
+ current_path: Internal parameter for tracking the current path during
+ recursion.
+
+ Returns:
+ A new dict with the merged values.
+ """
+ if replace_paths is None:
+ replace_paths = frozenset()
+
return {
- key: _merge_key(original, update, key)
+ key: _merge_key(original, update, key, replace_paths, current_path)
for key in set(original.keys()).union(set(update.keys()))
}
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 2781a9f4d2..dff3dfc95c 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -104,8 +104,9 @@ components:
\ the Google AI config\n - `bedrock`: the Bedrock config\n - `azure`:\
\ the Azure config\n - `ollama`: the Ollama config\n - `github`: the\
\ GitHub config\n - `openrouter`: the OpenRouter config\n - `wandb`:\
- \ the Weights & Biases config\n - `open_ai_compatible`: the OpenAI-compatible\
- \ config"
+ \ the Weights & Biases config\n - `custom_providers`: a dict of custom\
+ \ OpenAI-compatible providers\n - `open_ai_compatible`: the OpenAI-compatible\
+ \ config (deprecated, use custom_providers)"
properties:
anthropic:
$ref: '#/components/schemas/AnthropicConfig'
@@ -113,6 +114,10 @@ components:
$ref: '#/components/schemas/OpenAiConfig'
bedrock:
$ref: '#/components/schemas/BedrockConfig'
+ custom_providers:
+ additionalProperties:
+ $ref: '#/components/schemas/OpenAiConfig'
+ type: object
github:
$ref: '#/components/schemas/GitHubConfig'
google:
@@ -5785,4 +5790,3 @@ paths:
summary: Submit login form
tags:
- auth
-
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index f3261a0b21..466921b908 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -2987,12 +2987,16 @@ export interface components {
* - `github`: the GitHub config
* - `openrouter`: the OpenRouter config
* - `wandb`: the Weights & Biases config
- * - `open_ai_compatible`: the OpenAI-compatible config
+ * - `custom_providers`: a dict of custom OpenAI-compatible providers
+ * - `open_ai_compatible`: the OpenAI-compatible config (deprecated, use custom_providers)
*/
AiConfig: {
anthropic?: components["schemas"]["AnthropicConfig"];
azure?: components["schemas"]["OpenAiConfig"];
bedrock?: components["schemas"]["BedrockConfig"];
+ custom_providers?: {
+ [key: string]: components["schemas"]["OpenAiConfig"];
+ };
github?: components["schemas"]["GitHubConfig"];
google?: components["schemas"]["GoogleAiConfig"];
inline_tooltip?: boolean;
diff --git a/tests/_config/test_config.py b/tests/_config/test_config.py
index 8fd59bf880..4e515238be 100644
--- a/tests/_config/test_config.py
+++ b/tests/_config/test_config.py
@@ -182,3 +182,127 @@ def test_merge_config_with_keymap_overrides() -> None:
assert new_config["keymap"]["preset"] == "vim"
assert new_config.get("keymap", {}).get("overrides", {}) == {}
+
+
+def test_merge_config_custom_providers_replaces_instead_of_merging() -> None:
+ """Test that custom_providers is replaced, not merged.
+
+ This is important because users can add/remove custom providers,
+ and we want the new config to completely replace the old one.
+ """
+ prev_config = merge_default_config(
+ PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "provider1": {
+ "api_key": "key1",
+ "base_url": "https://api1.example.com",
+ },
+ "provider2": {
+ "api_key": "key2",
+ "base_url": "https://api2.example.com",
+ },
+ },
+ },
+ )
+ )
+
+ # Verify initial state
+ custom_providers = prev_config.get("ai", {}).get("custom_providers", {})
+ assert "provider1" in custom_providers
+ assert "provider2" in custom_providers
+
+ # Update with only provider1 (removing provider2)
+ new_config = merge_config(
+ prev_config,
+ PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "provider1": {
+ "api_key": "key1_updated",
+ "base_url": "https://api1.example.com",
+ },
+ # provider2 is intentionally removed
+ },
+ },
+ ),
+ )
+
+ # provider2 should be gone (replaced, not merged)
+ new_custom_providers = new_config.get("ai", {}).get("custom_providers", {})
+ assert "provider1" in new_custom_providers
+ assert "provider2" not in new_custom_providers
+ assert new_custom_providers["provider1"]["api_key"] == "key1_updated"
+
+
+def test_merge_config_custom_providers_can_be_emptied() -> None:
+ """Test that custom_providers can be set to empty dict."""
+ prev_config = merge_default_config(
+ PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "provider1": {
+ "api_key": "key1",
+ "base_url": "https://api1.example.com",
+ },
+ },
+ },
+ )
+ )
+
+ # Update with empty custom_providers
+ new_config = merge_config(
+ prev_config,
+ PartialMarimoConfig(
+ ai={
+ "custom_providers": {},
+ },
+ ),
+ )
+
+ # custom_providers should be empty
+ assert new_config.get("ai", {}).get("custom_providers", {}) == {}
+
+
+def test_merge_config_custom_providers_preserves_other_ai_settings() -> None:
+ """Test that updating custom_providers doesn't affect other AI settings."""
+ prev_config = merge_default_config(
+ PartialMarimoConfig(
+ ai={
+ "open_ai": {
+ "api_key": "openai_key",
+ },
+ "custom_providers": {
+ "provider1": {
+ "api_key": "key1",
+ "base_url": "https://api1.example.com",
+ },
+ },
+ },
+ )
+ )
+
+ # Update only custom_providers
+ new_config = merge_config(
+ prev_config,
+ PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "provider2": {
+ "api_key": "key2",
+ "base_url": "https://api2.example.com",
+ },
+ },
+ },
+ ),
+ )
+
+ # OpenAI config should be preserved
+ assert (
+ new_config.get("ai", {}).get("open_ai", {}).get("api_key")
+ == "openai_key"
+ )
+ # custom_providers should be replaced
+ custom_providers = new_config.get("ai", {}).get("custom_providers", {})
+ assert "provider1" not in custom_providers
+ assert "provider2" in custom_providers
diff --git a/tests/_config/test_secrets_config.py b/tests/_config/test_secrets_config.py
index 4a22f08aac..fa2dbd098b 100644
--- a/tests/_config/test_secrets_config.py
+++ b/tests/_config/test_secrets_config.py
@@ -143,3 +143,111 @@ def test_remove_secret_placeholders() -> None:
assert config["ai"]["google"]["api_key"] == SECRET_PLACEHOLDER
assert config["ai"]["anthropic"]["api_key"] == SECRET_PLACEHOLDER
assert config["ai"]["openrouter"]["api_key"] == SECRET_PLACEHOLDER
+
+
+def test_mask_secrets_custom_providers() -> None:
+ """Test that custom_providers api_keys are masked."""
+ config = PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "groq": {
+ "api_key": "gsk-super-secret-groq-key",
+ "base_url": "https://api.groq.com/openai/v1",
+ },
+ "together": {
+ "api_key": "tg-super-secret-together-key",
+ "base_url": "https://api.together.xyz/v1",
+ },
+ "local_provider": {
+ "base_url": "http://localhost:8000/v1",
+ # no api_key
+ },
+ },
+ },
+ )
+
+ # Verify original values
+ assert (
+ config["ai"]["custom_providers"]["groq"]["api_key"]
+ == "gsk-super-secret-groq-key"
+ )
+ assert (
+ config["ai"]["custom_providers"]["together"]["api_key"]
+ == "tg-super-secret-together-key"
+ )
+
+ # Mask secrets
+ new_config = mask_secrets(config)
+
+ # Verify api_keys are masked
+ assert (
+ new_config["ai"]["custom_providers"]["groq"]["api_key"]
+ == SECRET_PLACEHOLDER
+ )
+ assert (
+ new_config["ai"]["custom_providers"]["together"]["api_key"]
+ == SECRET_PLACEHOLDER
+ )
+
+ # Verify base_url is not masked
+ assert (
+ new_config["ai"]["custom_providers"]["groq"]["base_url"]
+ == "https://api.groq.com/openai/v1"
+ )
+ assert (
+ new_config["ai"]["custom_providers"]["together"]["base_url"]
+ == "https://api.together.xyz/v1"
+ )
+
+ # Verify provider without api_key is unchanged
+ assert (
+ new_config["ai"]["custom_providers"]["local_provider"]["base_url"]
+ == "http://localhost:8000/v1"
+ )
+ assert (
+ "api_key" not in new_config["ai"]["custom_providers"]["local_provider"]
+ )
+
+ # Ensure the original config is not modified
+ assert (
+ config["ai"]["custom_providers"]["groq"]["api_key"]
+ == "gsk-super-secret-groq-key"
+ )
+ assert (
+ config["ai"]["custom_providers"]["together"]["api_key"]
+ == "tg-super-secret-together-key"
+ )
+
+
+def test_remove_secret_placeholders_custom_providers() -> None:
+ """Test that custom_providers secret placeholders are removed."""
+ config = PartialMarimoConfig(
+ ai={
+ "custom_providers": {
+ "groq": {
+ "api_key": SECRET_PLACEHOLDER,
+ "base_url": "https://api.groq.com/openai/v1",
+ },
+ },
+ },
+ )
+ assert (
+ config["ai"]["custom_providers"]["groq"]["api_key"]
+ == SECRET_PLACEHOLDER
+ )
+
+ new_config = remove_secret_placeholders(config)
+
+ # api_key should be removed
+ assert "api_key" not in new_config["ai"]["custom_providers"]["groq"]
+ # base_url should still be there
+ assert (
+ new_config["ai"]["custom_providers"]["groq"]["base_url"]
+ == "https://api.groq.com/openai/v1"
+ )
+
+ # Ensure the original config is not modified
+ assert (
+ config["ai"]["custom_providers"]["groq"]["api_key"]
+ == SECRET_PLACEHOLDER
+ )
diff --git a/tests/_server/templates/snapshots/export1.txt b/tests/_server/templates/snapshots/export1.txt
index 4aab0b03ef..85234325ff 100644
--- a/tests/_server/templates/snapshots/export1.txt
+++ b/tests/_server/templates/snapshots/export1.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_server/templates/snapshots/export2.txt b/tests/_server/templates/snapshots/export2.txt
index e85e87d8b3..27aa64783e 100644
--- a/tests/_server/templates/snapshots/export2.txt
+++ b/tests/_server/templates/snapshots/export2.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_server/templates/snapshots/export3.txt b/tests/_server/templates/snapshots/export3.txt
index ad13daaa7b..7f18dc4458 100644
--- a/tests/_server/templates/snapshots/export3.txt
+++ b/tests/_server/templates/snapshots/export3.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_server/templates/snapshots/export4.txt b/tests/_server/templates/snapshots/export4.txt
index 2614f90144..f65783cdd5 100644
--- a/tests/_server/templates/snapshots/export4.txt
+++ b/tests/_server/templates/snapshots/export4.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"css_file": "custom.css", "sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_server/templates/snapshots/export5.txt b/tests/_server/templates/snapshots/export5.txt
index deac19e47a..de5af5c1bb 100644
--- a/tests/_server/templates/snapshots/export5.txt
+++ b/tests/_server/templates/snapshots/export5.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"app_title": "My App", "html_head_file": "head.html", "sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_server/templates/snapshots/export6.txt b/tests/_server/templates/snapshots/export6.txt
index 5897b333b5..71a55cb195 100644
--- a/tests/_server/templates/snapshots/export6.txt
+++ b/tests/_server/templates/snapshots/export6.txt
@@ -59,7 +59,7 @@
"mode": "read",
"version": "0.0.0",
"serverToken": "token",
- "config": {"ai": {"models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "custom_css": ["custom1.css", "custom2.css"], "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+ "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "custom_css": ["custom1.css", "custom2.css"], "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "pixi"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
"configOverrides": {"formatting": {"line_length": 100}},
"appConfig": {"sql_output": "auto", "width": "compact"},
"view": {"showAppCode": true},
diff --git a/tests/_utils/test_deep_merge.py b/tests/_utils/test_deep_merge.py
new file mode 100644
index 0000000000..46c6317b2f
--- /dev/null
+++ b/tests/_utils/test_deep_merge.py
@@ -0,0 +1,211 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._utils.deep_merge import deep_merge
+
+
+def test_deep_merge_basic() -> None:
+ """Test basic deep merge functionality."""
+ original = {"a": 1, "b": {"c": 2, "d": 3}}
+ update = {"b": {"c": 10, "e": 4}, "f": 5}
+
+ result = deep_merge(original, update)
+
+ assert result == {"a": 1, "b": {"c": 10, "d": 3, "e": 4}, "f": 5}
+
+
+def test_deep_merge_keeps_original_keys_not_in_update() -> None:
+ """Test that keys in original but not in update are preserved."""
+ original = {"a": 1, "b": 2, "c": 3}
+ update = {"b": 20}
+
+ result = deep_merge(original, update)
+
+ assert result == {"a": 1, "b": 20, "c": 3}
+
+
+def test_deep_merge_adds_new_keys_from_update() -> None:
+ """Test that new keys in update are added."""
+ original = {"a": 1}
+ update = {"b": 2}
+
+ result = deep_merge(original, update)
+
+ assert result == {"a": 1, "b": 2}
+
+
+def test_deep_merge_nested_dicts() -> None:
+ """Test deep merge with nested dictionaries."""
+ original = {
+ "level1": {
+ "level2": {
+ "keep": "original",
+ "override": "original",
+ }
+ }
+ }
+ update = {
+ "level1": {
+ "level2": {
+ "override": "updated",
+ "new": "added",
+ }
+ }
+ }
+
+ result = deep_merge(original, update)
+
+ assert result == {
+ "level1": {
+ "level2": {
+ "keep": "original",
+ "override": "updated",
+ "new": "added",
+ }
+ }
+ }
+
+
+def test_deep_merge_replace_paths_replaces_instead_of_merging() -> None:
+ """Test that paths in replace_paths are replaced, not merged."""
+ original = {
+ "ai": {
+ "custom_providers": {
+ "provider1": {"api_key": "key1", "base_url": "url1"},
+ "provider2": {"api_key": "key2", "base_url": "url2"},
+ }
+ }
+ }
+ update = {
+ "ai": {
+ "custom_providers": {
+ "provider1": {"api_key": "key1_updated", "base_url": "url1"},
+ # provider2 is removed
+ }
+ }
+ }
+
+ # Without replace_paths, provider2 would be kept
+ result_merged = deep_merge(original, update)
+ assert "provider2" in result_merged["ai"]["custom_providers"]
+
+ # With replace_paths, provider2 should be removed
+ result_replaced = deep_merge(
+ original, update, replace_paths=frozenset({"ai.custom_providers"})
+ )
+ assert "provider2" not in result_replaced["ai"]["custom_providers"]
+ assert result_replaced["ai"]["custom_providers"] == {
+ "provider1": {"api_key": "key1_updated", "base_url": "url1"}
+ }
+
+
+def test_deep_merge_replace_paths_with_empty_dict() -> None:
+ """Test that replace_paths works when update has empty dict."""
+ original = {
+ "ai": {
+ "custom_providers": {
+ "provider1": {"api_key": "key1"},
+ }
+ }
+ }
+ update = {
+ "ai": {
+ "custom_providers": {} # Remove all providers
+ }
+ }
+
+ result = deep_merge(
+ original, update, replace_paths=frozenset({"ai.custom_providers"})
+ )
+
+ assert result["ai"]["custom_providers"] == {}
+
+
+def test_deep_merge_replace_paths_does_not_affect_other_paths() -> None:
+ """Test that replace_paths only affects specified paths."""
+ original = {
+ "ai": {
+ "custom_providers": {"p1": {"key": "v1"}},
+ "models": {"m1": "model1", "m2": "model2"},
+ }
+ }
+ update = {
+ "ai": {
+ "custom_providers": {"p2": {"key": "v2"}},
+ "models": {"m1": "updated"},
+ # m2 not in update
+ }
+ }
+
+ result = deep_merge(
+ original, update, replace_paths=frozenset({"ai.custom_providers"})
+ )
+
+ # custom_providers should be replaced (p1 gone, only p2)
+ assert result["ai"]["custom_providers"] == {"p2": {"key": "v2"}}
+ # models should be merged (m2 kept, m1 updated)
+ assert result["ai"]["models"] == {"m1": "updated", "m2": "model2"}
+
+
+def test_deep_merge_replace_paths_nested_path() -> None:
+ """Test replace_paths with deeply nested paths."""
+ original = {
+ "a": {
+ "b": {
+ "c": {
+ "keep": "original",
+ "replace_me": {"x": 1, "y": 2},
+ }
+ }
+ }
+ }
+ update = {
+ "a": {
+ "b": {
+ "c": {
+ "replace_me": {"z": 3},
+ }
+ }
+ }
+ }
+
+ result = deep_merge(
+ original, update, replace_paths=frozenset({"a.b.c.replace_me"})
+ )
+
+ # replace_me should be replaced entirely
+ assert result["a"]["b"]["c"]["replace_me"] == {"z": 3}
+ # keep should be preserved (it's not in update, and parent is not replaced)
+ assert result["a"]["b"]["c"]["keep"] == "original"
+
+
+def test_deep_merge_replace_paths_when_key_not_in_original() -> None:
+ """Test replace_paths when the key doesn't exist in original."""
+ original = {"a": {"other": "value"}}
+ update = {"a": {"custom_providers": {"p1": {"key": "v1"}}}}
+
+ result = deep_merge(
+ original, update, replace_paths=frozenset({"a.custom_providers"})
+ )
+
+ assert result == {
+ "a": {"other": "value", "custom_providers": {"p1": {"key": "v1"}}}
+ }
+
+
+def test_deep_merge_replace_paths_when_key_not_in_update() -> None:
+ """Test replace_paths when the key doesn't exist in update."""
+ original = {"a": {"custom_providers": {"p1": {"key": "v1"}}}}
+ update = {"a": {"other": "new_value"}}
+
+ result = deep_merge(
+ original, update, replace_paths=frozenset({"a.custom_providers"})
+ )
+
+ # custom_providers should be kept since it's not in update
+ assert result == {
+ "a": {
+ "custom_providers": {"p1": {"key": "v1"}},
+ "other": "new_value",
+ }
+ }