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.

feat(ai): read provider keys from environment variables (#10665)

Shahmir Varqha9b2a7ac65672
diff --git a/docs/guides/configuration/llm_providers.md b/docs/guides/configuration/llm_providers.md
index 40283c2035..1a50c8526c 100644
--- a/docs/guides/configuration/llm_providers.md
+++ b/docs/guides/configuration/llm_providers.md
@@ -52,6 +52,52 @@ rules = """
max_tokens = 1000
```
+## API keys from environment variables
+
+Some providers use a default environment variable when `api_key` is not set.
+
+| Provider | Environment variable |
+| --- | --- |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Google AI | `GEMINI_API_KEY`, then `GOOGLE_API_KEY` |
+| Azure OpenAI | `AZURE_API_KEY` |
+| GitHub | `GITHUB_TOKEN` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Weights & Biases | `WANDB_API_KEY` |
+| OpenCode Go | `OPENCODE_API_KEY` |
+
+For example, you can configure OpenAI without an `api_key` value:
+
+```bash
+export OPENAI_API_KEY="sk-proj-..."
+marimo edit notebook.py
+```
+
+You can also use a different environment variable. Set `api_key` to an
+`env:` reference:
+
+```toml title="marimo.toml"
+[ai.custom_providers.enterprise_gateway]
+api_key = "env:ENTERPRISE_AI_API_KEY"
+base_url = "https://gateway.example.com/v1"
+```
+
+The `env:` syntax works with each provider that accepts `api_key`. This
+includes custom providers. marimo returns a configuration error when the
+referenced variable is empty or absent.
+
+The `env:` prefix is reserved for environment variable references. A literal
+API key cannot start with this prefix.
+
+!!! warning "Use trusted configuration"
+ Use `env:` references only in configuration files that you trust. A provider
+ sends the resolved value to its configured endpoint.
+
+marimo first reads the environment of the server process. Then marimo reads
+the configured [`.env` files](runtime_configuration.md#env-files) in order.
+The first value takes precedence.
+
## Supported providers
<div align="center">
diff --git a/marimo/_config/config.py b/marimo/_config/config.py
index 17a26cf9fb..3231f2214a 100644
--- a/marimo/_config/config.py
+++ b/marimo/_config/config.py
@@ -360,7 +360,7 @@ class OpenAiConfig(TypedDict, total=False):
**Keys.**
- - `api_key`: the OpenAI API key
+ - `api_key`: the OpenAI API key or an `env:` reference
- `base_url`: the base URL for the API
- `project`: the project ID for the OpenAI API
- `ssl_verify` : Boolean argument for httpx passed to open ai client. httpx defaults to true, but some use cases to let users override to False in some testing scenarios
@@ -387,7 +387,7 @@ class AnthropicConfig(TypedDict, total=False):
**Keys.**
- - `api_key`: the Anthropic API key
+ - `api_key`: the Anthropic API key or an `env:` reference
"""
api_key: str
@@ -399,7 +399,7 @@ class GoogleAiConfig(TypedDict, total=False):
**Keys.**
- - `api_key`: the Google AI API key
+ - `api_key`: the Google AI API key or an `env:` reference
"""
api_key: str
@@ -429,7 +429,7 @@ class GitHubConfig(TypedDict, total=False):
**Keys.**
- - `api_key`: the GitHub API token
+ - `api_key`: the GitHub API token or an `env:` reference
- `base_url`: the base URL for the API
- `copilot_settings`: configuration settings for GitHub Copilot LSP.
Supports settings like `http` (proxy configuration), `telemetry`,
diff --git a/marimo/_secrets/env_provider.py b/marimo/_secrets/env_provider.py
index 1f07ed8589..3df5cf0ac9 100644
--- a/marimo/_secrets/env_provider.py
+++ b/marimo/_secrets/env_provider.py
@@ -2,6 +2,7 @@
from __future__ import annotations
from pathlib import Path
+from typing import TYPE_CHECKING
from marimo._secrets.load_dotenv import (
escape_dotenv_value,
@@ -9,11 +10,14 @@ from marimo._secrets.load_dotenv import (
)
from marimo._secrets.models import SecretProvider
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
class EnvSecretsProvider(SecretProvider):
type = "env"
- def __init__(self, original_environ: dict[str, str]):
+ def __init__(self, original_environ: Mapping[str, str]):
self.original_environ = original_environ
@property
diff --git a/marimo/_secrets/load_dotenv.py b/marimo/_secrets/load_dotenv.py
index 764915fd37..e094be7a67 100644
--- a/marimo/_secrets/load_dotenv.py
+++ b/marimo/_secrets/load_dotenv.py
@@ -3,39 +3,123 @@ from __future__ import annotations
import os
import re
+from functools import partial
+from typing import TYPE_CHECKING
from marimo._dependencies.dependencies import DependencyManager
+if TYPE_CHECKING:
+ from collections.abc import Iterable, Mapping, Sequence
+
+
+_POSIX_VARIABLE = re.compile(
+ r"\$\{(?P<name>[^}:]*)(?::-(?P<default>[^}]*))?\}"
+)
+
def load_dotenv_with_fallback(file: str) -> None:
"""Load a .env file using the dotenv library, falling to our custom
implementation if the dotenv library is not installed.
"""
- if DependencyManager.dotenv.has():
- from dotenv import load_dotenv
+ load_to_environ(read_dotenv_with_fallback(file, environment=os.environ))
- # By default, load_dotenv does not override existing keys in the
- # environment.
- load_dotenv(file)
- else:
- load_to_environ(parse_dotenv(file))
-
-def read_dotenv_with_fallback(file: str) -> dict[str, str | None]:
+def read_dotenv_with_fallback(
+ file: str,
+ *,
+ environment: Mapping[str, str | None] | None = None,
+) -> dict[str, str | None]:
"""Read a .env file using the dotenv library, falling to our custom
implementation if the dotenv library is not installed.
"""
- if DependencyManager.dotenv.has():
- from dotenv import dotenv_values
+ environment_overrides = environment is not None
+ return _interpolate_dotenv_values(
+ _read_dotenv_bindings(file),
+ os.environ if environment is None else environment,
+ environment_overrides=environment_overrides,
+ )
+
+
+def resolve_dotenv_value(
+ key: str,
+ files: Sequence[str],
+ environment: Mapping[str, str],
+) -> str | None:
+ """Resolve one value using environment and dotenv file precedence."""
+ resolved = dict(environment)
+ if key in resolved:
+ return resolved[key]
+
+ for file in files:
+ file_values = read_dotenv_with_fallback(file, environment=resolved)
+ for name, value in file_values.items():
+ if name not in resolved and value is not None:
+ resolved[name] = value
+ if key in resolved:
+ return resolved[key]
+
+ return None
+
+
+def _interpolate_dotenv_values(
+ values: Iterable[tuple[str, str | None]],
+ environment: Mapping[str, str | None],
+ *,
+ environment_overrides: bool,
+) -> dict[str, str | None]:
+ resolved: dict[str, str | None] = {}
+ for key, value in values:
+ if value is None:
+ resolved[key] = None
+ continue
+
+ if environment_overrides:
+ # Match `load_dotenv(..., override=False)` when resolving a chain.
+ interpolation_environment = {**resolved, **environment}
+ else:
+ # Preserve `dotenv_values` behavior for existing callers.
+ interpolation_environment = {**environment, **resolved}
+ resolved[key] = _POSIX_VARIABLE.sub(
+ partial(_resolve_variable, environment=interpolation_environment),
+ value,
+ )
+ return resolved
+
+
+def _resolve_variable(
+ match: re.Match[str], environment: Mapping[str, str | None]
+) -> str:
+ default = match.group("default") or ""
+ value = environment.get(match.group("name"), default)
+ return "" if value is None else value
+
+
+def _read_dotenv_bindings(file: str) -> list[tuple[str, str | None]]:
+ """Read bindings in source order, including duplicate assignments."""
+ if not DependencyManager.dotenv.has():
+ return list(_parse_dotenv_bindings(file))
- return dotenv_values(file)
- else:
- return parse_dotenv(file)
+ from dotenv.parser import parse_stream
+
+ try:
+ with open(file, encoding="utf-8") as stream:
+ return [
+ (binding.key, binding.value)
+ for binding in parse_stream(stream)
+ if binding.key is not None and not binding.error
+ ]
+ except FileNotFoundError:
+ return []
def parse_dotenv(filepath: str) -> dict[str, str | None]:
"""Parse a .env file into a dictionary of key-value pairs."""
- env_dict: dict[str, str | None] = {}
+ return dict(_parse_dotenv_bindings(filepath))
+
+
+def _parse_dotenv_bindings(
+ filepath: str,
+) -> Iterable[tuple[str, str | None]]:
try:
with open(filepath, encoding="utf-8") as f:
for line in f:
@@ -54,11 +138,10 @@ def parse_dotenv(filepath: str) -> dict[str, str | None]:
continue
value = _drop_quotes(value.strip())
- env_dict[key] = value
+ yield key, value
except FileNotFoundError:
# Handle case where .env file doesn't exist
- pass
- return env_dict
+ return
def load_to_environ(env_dict: dict[str, str | None]) -> None:
diff --git a/marimo/_secrets/secrets.py b/marimo/_secrets/secrets.py
index baaaadeb88..775075825a 100644
--- a/marimo/_secrets/secrets.py
+++ b/marimo/_secrets/secrets.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import os
from typing import TYPE_CHECKING
from marimo import _loggers
@@ -9,16 +10,19 @@ from marimo._secrets.env_provider import (
DotEnvSecretsProvider,
EnvSecretsProvider,
)
+from marimo._secrets.load_dotenv import resolve_dotenv_value
from marimo._secrets.models import SecretKeysWithProvider, SecretProvider
LOGGER = _loggers.marimo_logger()
if TYPE_CHECKING:
+ from collections.abc import Mapping
+
from marimo._server.models.secrets import CreateSecretRequest
def _get_providers(
- config: MarimoConfig, original_environ: dict[str, str]
+ config: MarimoConfig, original_environ: Mapping[str, str]
) -> list[SecretProvider]:
providers: list[SecretProvider] = [EnvSecretsProvider(original_environ)]
@@ -30,6 +34,23 @@ def _get_providers(
return providers
+def get_secret_value(
+ key: str,
+ config: MarimoConfig,
+ environ: Mapping[str, str] | None = None,
+) -> str | None:
+ """Resolve a secret using marimo's environment and dotenv precedence.
+
+ Dotenv values are read on demand so callers observe key rotation without
+ mutating the server's process environment.
+ """
+ base_environment = os.environ if environ is None else environ
+ dotenvs = config.get("runtime", {}).get("dotenv", [])
+ if not isinstance(dotenvs, list):
+ dotenvs = []
+ return resolve_dotenv_value(key, dotenvs, base_environment)
+
+
def get_secret_keys(
config: MarimoConfig, original_environ: dict[str, str]
) -> list[SecretKeysWithProvider]:
diff --git a/marimo/_server/ai/config.py b/marimo/_server/ai/config.py
index 4c59251b71..828146e6b2 100644
--- a/marimo/_server/ai/config.py
+++ b/marimo/_server/ai/config.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from collections.abc import Callable
from dataclasses import dataclass
from typing import (
Any,
@@ -23,6 +24,9 @@ from marimo._utils.http import HTTPStatus
# https://github.com/pydantic/pydantic-ai/blob/8b9ac2bde2355b0d431abea6cf210a36fffe0c43/pydantic_ai_slim/pydantic_ai/providers/github.py#L41C17-L41C51
GITHUB_COPILOT_BASE_URL = "https://models.github.ai/inference"
+ENV_SECRET_PREFIX = "env:"
+
+SecretResolver = Callable[[str], str | None]
@dataclass
@@ -46,36 +50,60 @@ class AnyProviderConfig:
self.tools = None
@classmethod
- def for_openai(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("OPENAI_API_KEY")
+ def for_openai(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret("OPENAI_API_KEY", secret_resolver)
return cls._for_openai_like(
config,
"open_ai",
"OpenAI",
fallback_key=fallback_key,
require_key=True,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_azure(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("AZURE_API_KEY")
+ def for_azure(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret("AZURE_API_KEY", secret_resolver)
return cls._for_openai_like(
config,
"azure",
"Azure OpenAI",
fallback_key=fallback_key,
require_key=True,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_openai_compatible(cls, config: AiConfig) -> AnyProviderConfig:
+ def for_openai_compatible(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
return cls._for_openai_like(
- config, "open_ai_compatible", "OpenAI Compatible"
+ config,
+ "open_ai_compatible",
+ "OpenAI Compatible",
+ secret_resolver=secret_resolver,
)
@classmethod
def for_custom_provider(
- cls, config: AiConfig, provider_name: str
+ cls,
+ config: AiConfig,
+ provider_name: str,
+ *,
+ secret_resolver: SecretResolver | None = None,
) -> AnyProviderConfig:
"""Get config for a custom provider by name."""
custom_providers = cast(
@@ -95,10 +123,16 @@ class AnyProviderConfig:
name=provider_name.replace("_", " ").title(),
require_key=False,
ai_config=provider_config,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_ollama(cls, config: AiConfig) -> AnyProviderConfig:
+ def for_ollama(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
default_base_url = "http://127.0.0.1:11434/v1"
return cls._for_openai_like(
config,
@@ -106,11 +140,17 @@ class AnyProviderConfig:
"Ollama",
fallback_key="ollama-placeholder",
fallback_base_url=default_base_url,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_github(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("GITHUB_TOKEN")
+ def for_github(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret("GITHUB_TOKEN", secret_resolver)
result = cls._for_openai_like(
config,
"github",
@@ -119,6 +159,7 @@ class AnyProviderConfig:
# Default base URL for GitHub Copilot, taken from
fallback_base_url=GITHUB_COPILOT_BASE_URL,
require_key=True,
+ secret_resolver=secret_resolver,
)
# Add default extra headers for GitHub, but allow user to override
@@ -137,8 +178,15 @@ class AnyProviderConfig:
return result
@classmethod
- def for_openrouter(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("OPENROUTER_API_KEY")
+ def for_openrouter(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret(
+ "OPENROUTER_API_KEY", secret_resolver
+ )
return cls._for_openai_like(
config,
"openrouter",
@@ -147,11 +195,17 @@ class AnyProviderConfig:
# Default base URL for OpenRouter
fallback_base_url="https://openrouter.ai/api/v1/",
require_key=True,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_wandb(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("WANDB_API_KEY")
+ def for_wandb(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret("WANDB_API_KEY", secret_resolver)
return cls._for_openai_like(
config,
"wandb",
@@ -160,11 +214,17 @@ class AnyProviderConfig:
# Default base URL for Weights & Biases
fallback_base_url="https://api.inference.wandb.ai/v1/",
require_key=True,
+ secret_resolver=secret_resolver,
)
@classmethod
- def for_opencode_go(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("OPENCODE_API_KEY")
+ def for_opencode_go(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret("OPENCODE_API_KEY", secret_resolver)
return cls._for_openai_like(
config,
"opencode_go",
@@ -173,6 +233,7 @@ class AnyProviderConfig:
# Default base URL for OpenCode Go
fallback_base_url="https://opencode.ai/zen/go/v1/",
require_key=True,
+ secret_resolver=secret_resolver,
)
@classmethod
@@ -186,10 +247,15 @@ class AnyProviderConfig:
fallback_base_url: str | None = None,
require_key: bool = False,
ai_config: dict[str, Any] | None = None,
+ secret_resolver: SecretResolver | None = None,
) -> AnyProviderConfig:
ai_config = ai_config or _get_ai_config(config, key)
key = _get_key(
- ai_config, name, fallback_key=fallback_key, require_key=require_key
+ ai_config,
+ name,
+ fallback_key=fallback_key,
+ require_key=require_key,
+ secret_resolver=secret_resolver,
)
# Use SSL_CERT_FILE environment variable as fallback for ca_bundle_path
@@ -211,14 +277,22 @@ class AnyProviderConfig:
return AnyProviderConfig(**kwargs)
@classmethod
- def for_anthropic(cls, config: AiConfig) -> AnyProviderConfig:
+ def for_anthropic(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
ai_config = _get_ai_config(config, "anthropic")
- fallback_key = cls.os_key("ANTHROPIC_API_KEY")
+ fallback_key = cls._resolve_secret(
+ "ANTHROPIC_API_KEY", secret_resolver
+ )
key = _get_key(
ai_config,
"Anthropic",
fallback_key=fallback_key,
require_key=True,
+ secret_resolver=secret_resolver,
)
return cls(
base_url=_get_base_url(ai_config),
@@ -227,16 +301,22 @@ class AnyProviderConfig:
)
@classmethod
- def for_google(cls, config: AiConfig) -> AnyProviderConfig:
- fallback_key = cls.os_key("GEMINI_API_KEY") or cls.os_key(
- "GOOGLE_API_KEY"
- )
+ def for_google(
+ cls,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
+ fallback_key = cls._resolve_secret(
+ "GEMINI_API_KEY", secret_resolver
+ ) or cls._resolve_secret("GOOGLE_API_KEY", secret_resolver)
ai_config = _get_ai_config(config, "google")
key = _get_key(
ai_config,
"Google AI",
fallback_key=fallback_key,
require_key=False,
+ secret_resolver=secret_resolver,
)
return cls(
base_url=_get_base_url(ai_config),
@@ -256,44 +336,63 @@ class AnyProviderConfig:
)
@classmethod
- def for_model(cls, model: str, config: AiConfig) -> AnyProviderConfig:
+ def for_model(
+ cls,
+ model: str,
+ config: AiConfig,
+ *,
+ secret_resolver: SecretResolver | None = None,
+ ) -> AnyProviderConfig:
model_id = AiModelId.from_model(model)
if model_id.provider == "anthropic":
- return cls.for_anthropic(config)
+ return cls.for_anthropic(config, secret_resolver=secret_resolver)
elif model_id.provider == "google":
- return cls.for_google(config)
+ return cls.for_google(config, secret_resolver=secret_resolver)
elif model_id.provider == "bedrock":
return cls.for_bedrock(config)
elif model_id.provider == "ollama":
- return cls.for_ollama(config)
+ return cls.for_ollama(config, secret_resolver=secret_resolver)
elif model_id.provider == "openai":
- return cls.for_openai(config)
+ return cls.for_openai(config, secret_resolver=secret_resolver)
elif model_id.provider == "azure":
- return cls.for_azure(config)
+ return cls.for_azure(config, secret_resolver=secret_resolver)
elif model_id.provider == "github":
- return cls.for_github(config)
+ return cls.for_github(config, secret_resolver=secret_resolver)
elif model_id.provider == "openrouter":
- return cls.for_openrouter(config)
+ return cls.for_openrouter(config, secret_resolver=secret_resolver)
elif model_id.provider == "wandb":
- return cls.for_wandb(config)
+ return cls.for_wandb(config, secret_resolver=secret_resolver)
elif model_id.provider == "opencode-go":
- return cls.for_opencode_go(config)
+ return cls.for_opencode_go(config, secret_resolver=secret_resolver)
elif model_id.provider == "openai_compatible":
- return cls.for_openai_compatible(config)
+ return cls.for_openai_compatible(
+ config, secret_resolver=secret_resolver
+ )
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)
+ return cls.for_custom_provider(
+ config,
+ model_id.provider,
+ secret_resolver=secret_resolver,
+ )
+
+ # Catch-all: use OpenAI compatible when it is configured.
+ if "open_ai_compatible" in config:
+ return cls.for_openai_compatible(
+ config, secret_resolver=secret_resolver
+ )
+ return cls.for_openai(config, secret_resolver=secret_resolver)
- # Catch-all: try OpenAI compatible first, then OpenAI.
- try:
- if "open_ai_compatible" in config:
- return cls.for_openai_compatible(config)
- return cls.for_openai(config)
- except HTTPException:
- return cls.for_openai(config)
+ @classmethod
+ def _resolve_secret(
+ cls, key: str, secret_resolver: SecretResolver | None
+ ) -> str | None:
+ if secret_resolver is not None:
+ return secret_resolver(key)
+ return cls.os_key(key)
@classmethod
def os_key(cls, key: str) -> str | None:
@@ -358,6 +457,7 @@ def _get_key(
*,
fallback_key: str | None = None,
require_key: bool = False,
+ secret_resolver: SecretResolver | None = None,
) -> str:
"""Get the API key for a given provider."""
if not isinstance(config, dict):
@@ -382,6 +482,26 @@ def _get_key(
if "api_key" in config:
key = config["api_key"]
if key:
+ if isinstance(key, str) and key.startswith(ENV_SECRET_PREFIX):
+ secret_name = key.removeprefix(ENV_SECRET_PREFIX)
+ if not secret_name:
+ raise HTTPException(
+ status_code=HTTPStatus.BAD_REQUEST,
+ detail=f"{name} API key has an empty environment variable reference.",
+ )
+
+ resolved_key = AnyProviderConfig._resolve_secret(
+ secret_name, secret_resolver
+ )
+ if not resolved_key:
+ raise HTTPException(
+ status_code=HTTPStatus.BAD_REQUEST,
+ detail=(
+ f"{name} API key environment variable "
+ f"'{secret_name}' is not set."
+ ),
+ )
+ return resolved_key
return cast(str, key)
if "http://127.0.0.1:11434/" in config.get("base_url", ""):
diff --git a/marimo/_server/api/endpoints/ai.py b/marimo/_server/api/endpoints/ai.py
index d3241936ed..bf6bc5912a 100644
--- a/marimo/_server/api/endpoints/ai.py
+++ b/marimo/_server/api/endpoints/ai.py
@@ -14,6 +14,7 @@ from starlette.responses import (
from marimo import _loggers
from marimo._ai._pydantic_ai_utils import create_simple_prompt, generate_id
from marimo._config.config import AiConfig, CopilotMode, MarimoConfig
+from marimo._secrets.secrets import get_secret_value
from marimo._server.ai.config import (
AnyProviderConfig,
get_autocomplete_model,
@@ -100,6 +101,14 @@ def get_ai_config(config: MarimoConfig) -> AiConfig:
return ai_config
+def get_provider_config(model: str, config: MarimoConfig) -> AnyProviderConfig:
+ return AnyProviderConfig.for_model(
+ model,
+ get_ai_config(config),
+ secret_resolver=lambda key: get_secret_value(key, config),
+ )
+
+
@router.post("/completion")
@requires("edit")
async def ai_completion(
@@ -154,7 +163,7 @@ async def ai_completion(
model = get_edit_model(ai_config)
provider = get_completion_provider(
- AnyProviderConfig.for_model(model, ai_config),
+ get_provider_config(model, config),
model=model,
)
@@ -236,7 +245,7 @@ async def ai_chat(
model = body.model or get_chat_model(ai_config)
provider = get_completion_provider(
- AnyProviderConfig.for_model(model, ai_config),
+ get_provider_config(model, config),
model=model,
)
additional_tools = body.tools or []
@@ -318,10 +327,8 @@ async def ai_inline_completion(
# of 4096, since it is smaller/faster for inline completions
INLINE_COMPLETION_MAX_TOKENS = 1024
- ai_config = get_ai_config(config)
-
model = get_autocomplete_model(config)
- provider_config = AnyProviderConfig.for_model(model, ai_config)
+ provider_config = get_provider_config(model, config)
# Inline completion never uses tools
if provider_config.tools:
provider_config.tools.clear()
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 8bb7beaa66..67f6bee801 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -252,7 +252,7 @@ components:
type: object
AnthropicConfig:
description: "Configuration options for Anthropic.\n\n **Keys.**\n\n -\
- \ `api_key`: the Anthropic API key"
+ \ `api_key`: the Anthropic API key or an `env:` reference"
properties:
api_key:
type: string
@@ -2481,10 +2481,10 @@ components:
type: object
GitHubConfig:
description: "Configuration options for GitHub.\n\n **Keys.**\n\n - `api_key`:\
- \ the GitHub API token\n - `base_url`: the base URL for the API\n -\
- \ `copilot_settings`: configuration settings for GitHub Copilot LSP.\n \
- \ Supports settings like `http` (proxy configuration), `telemetry`,\n\
- \ and `github-enterprise` (enterprise URI)."
+ \ the GitHub API token or an `env:` reference\n - `base_url`: the base\
+ \ URL for the API\n - `copilot_settings`: configuration settings for GitHub\
+ \ Copilot LSP.\n Supports settings like `http` (proxy configuration),\
+ \ `telemetry`,\n and `github-enterprise` (enterprise URI)."
properties:
api_key:
type: string
@@ -2497,7 +2497,7 @@ components:
type: object
GoogleAiConfig:
description: "Configuration options for Google AI.\n\n **Keys.**\n\n -\
- \ `api_key`: the Google AI API key"
+ \ `api_key`: the Google AI API key or an `env:` reference"
properties:
api_key:
type: string
@@ -4145,15 +4145,15 @@ components:
type: object
OpenAiConfig:
description: "Configuration options for OpenAI or OpenAI-compatible services.\n\
- \n **Keys.**\n\n - `api_key`: the OpenAI API key\n - `base_url`:\
- \ the base URL for the API\n - `project`: the project ID for the OpenAI\
- \ API\n - `ssl_verify` : Boolean argument for httpx passed to open ai client.\
- \ httpx defaults to true, but some use cases to let users override to False\
- \ in some testing scenarios\n - `ca_bundle_path`: custom ca bundle to be\
- \ used for verifying SSL certificates. Used to create custom SSL context for\
- \ httpx client\n - `client_pem` : custom path of a client .pem cert used\
- \ for verifying identity of client server\n - `extra_headers`: extra headers\
- \ to be passed to the OpenAI client"
+ \n **Keys.**\n\n - `api_key`: the OpenAI API key or an `env:` reference\n\
+ \ - `base_url`: the base URL for the API\n - `project`: the project\
+ \ ID for the OpenAI API\n - `ssl_verify` : Boolean argument for httpx passed\
+ \ to open ai client. httpx defaults to true, but some use cases to let users\
+ \ override to False in some testing scenarios\n - `ca_bundle_path`: custom\
+ \ ca bundle to be used for verifying SSL certificates. Used to create custom\
+ \ SSL context for httpx client\n - `client_pem` : custom path of a client\
+ \ .pem cert used for verifying identity of client server\n - `extra_headers`:\
+ \ extra headers to be passed to the OpenAI client"
properties:
api_key:
type: string
@@ -7956,4 +7956,3 @@ paths:
summary: Get the auth token for the current session
tags:
- auth
-
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 1d0b69177e..76959e90e4 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3819,7 +3819,7 @@ export interface components {
*
* **Keys.**
*
- * - `api_key`: the Anthropic API key
+ * - `api_key`: the Anthropic API key or an `env:` reference
*/
AnthropicConfig: {
api_key?: string;
@@ -5149,7 +5149,7 @@ export interface components {
*
* **Keys.**
*
- * - `api_key`: the GitHub API token
+ * - `api_key`: the GitHub API token or an `env:` reference
* - `base_url`: the base URL for the API
* - `copilot_settings`: configuration settings for GitHub Copilot LSP.
* Supports settings like `http` (proxy configuration), `telemetry`,
@@ -5166,7 +5166,7 @@ export interface components {
*
* **Keys.**
*
- * - `api_key`: the Google AI API key
+ * - `api_key`: the Google AI API key or an `env:` reference
*/
GoogleAiConfig: {
api_key?: string;
@@ -6151,7 +6151,7 @@ export interface components {
*
* **Keys.**
*
- * - `api_key`: the OpenAI API key
+ * - `api_key`: the OpenAI API key or an `env:` reference
* - `base_url`: the base URL for the API
* - `project`: the project ID for the OpenAI API
* - `ssl_verify` : Boolean argument for httpx passed to open ai client. httpx defaults to true, but some use cases to let users override to False in some testing scenarios
diff --git a/tests/_secrets/test_load_dotenv.py b/tests/_secrets/test_load_dotenv.py
index 7125a33ee9..4f8436a639 100644
--- a/tests/_secrets/test_load_dotenv.py
+++ b/tests/_secrets/test_load_dotenv.py
@@ -13,6 +13,7 @@ from marimo._secrets.load_dotenv import (
load_to_environ,
parse_dotenv,
read_dotenv_with_fallback,
+ resolve_dotenv_value,
)
if TYPE_CHECKING:
@@ -100,6 +101,97 @@ def test_read_dotenv_with_fallback(tmp_path: Path):
assert env_dict == {"TEST_KEY": "test_value"}
+def test_read_dotenv_interpolates_from_environment(tmp_path: Path):
+ env_file = tmp_path / ".env"
+ env_file.write_text(
+ "FROM_ENV=${BASE}/env\nLOCAL=local\nFROM_FILE=${LOCAL}/file",
+ encoding="utf-8",
+ )
+
+ env_dict = read_dotenv_with_fallback(
+ str(env_file), environment={"BASE": "base"}
+ )
+
+ assert env_dict == {
+ "FROM_ENV": "base/env",
+ "LOCAL": "local",
+ "FROM_FILE": "local/file",
+ }
+
+
+def test_read_dotenv_interpolates_duplicate_assignments_in_order(
+ tmp_path: Path,
+) -> None:
+ env_file = tmp_path / ".env"
+ env_file.write_text(
+ "A=first\nB=${A}\nA=second\nC=${A}",
+ encoding="utf-8",
+ )
+
+ env_dict = read_dotenv_with_fallback(str(env_file), environment={})
+
+ assert env_dict == {
+ "A": "second",
+ "B": "first",
+ "C": "second",
+ }
+
+
+def test_resolve_dotenv_value_preserves_precedence_and_interpolation(
+ tmp_path: Path,
+) -> None:
+ first_env = tmp_path / ".env.first"
+ first_env.write_text(
+ "BASE=first\nENV_WINS=first",
+ encoding="utf-8",
+ )
+ second_env = tmp_path / ".env.second"
+ second_env.write_text(
+ "BASE=second\nDERIVED=${BASE}/second\nENV_WINS=second",
+ encoding="utf-8",
+ )
+
+ resolved = resolve_dotenv_value(
+ "DERIVED",
+ [str(first_env), str(second_env)],
+ {"ENV_WINS": "environment"},
+ )
+
+ assert resolved == "first/second"
+
+
+def test_resolve_dotenv_value_stops_after_environment_value(
+ tmp_path: Path,
+) -> None:
+ unreadable = tmp_path / "not-a-file"
+ unreadable.mkdir()
+
+ resolved = resolve_dotenv_value(
+ "API_KEY",
+ [str(unreadable)],
+ {"API_KEY": "environment"},
+ )
+
+ assert resolved == "environment"
+
+
+def test_resolve_dotenv_value_stops_after_first_dotenv_value(
+ tmp_path: Path,
+) -> None:
+ first_env = tmp_path / ".env.first"
+ first_env.write_text("API_KEY=first", encoding="utf-8")
+ unreadable = tmp_path / "not-a-file"
+ unreadable.mkdir()
+
+ resolved = resolve_dotenv_value(
+ "API_KEY",
+ [str(first_env), str(unreadable)],
+ {},
+ )
+
+ assert resolved == "first"
+
+
ROUND_TRIP_VALUES = [
"simple",
'json {"type": "service_account", "id": 1}',
diff --git a/tests/_secrets/test_secrets.py b/tests/_secrets/test_secrets.py
index 74d234d80d..fac5b90c53 100644
--- a/tests/_secrets/test_secrets.py
+++ b/tests/_secrets/test_secrets.py
@@ -6,7 +6,11 @@ from typing import TYPE_CHECKING
import pytest
from marimo._config.config import MarimoConfig
-from marimo._secrets.secrets import get_secret_keys, write_secret
+from marimo._secrets.secrets import (
+ get_secret_keys,
+ get_secret_value,
+ write_secret,
+)
from marimo._server.models.secrets import CreateSecretRequest
if TYPE_CHECKING:
@@ -131,6 +135,59 @@ def test_get_secret_keys_multiple_dotenv(
assert "SHARED_SECRET" not in result[2].keys
+def test_get_secret_value_uses_environment_then_dotenv(tmp_path: Path):
+ env_file = tmp_path / ".env"
+ env_file.write_text(
+ "ENV_FIRST=dotenv-value\nDOTENV_ONLY=dotenv-only",
+ encoding="utf-8",
+ )
+ environ = {"ENV_FIRST": "environment-value"}
+ config = MarimoConfig(runtime={"dotenv": [str(env_file)]})
+
+ assert (
+ get_secret_value("ENV_FIRST", config, environ) == "environment-value"
+ )
+ assert get_secret_value("DOTENV_ONLY", config, environ) == "dotenv-only"
+ assert get_secret_value("MISSING", config, environ) is None
+ assert "DOTENV_ONLY" not in environ
+
+
+def test_get_secret_value_uses_first_dotenv(tmp_path: Path):
+ first_env = tmp_path / ".env.first"
+ first_env.write_text("SHARED=first", encoding="utf-8")
+ second_env = tmp_path / ".env.second"
+ second_env.write_text("SHARED=second", encoding="utf-8")
+ config = MarimoConfig(
+ runtime={"dotenv": [str(first_env), str(second_env)]}
+ )
+
+ assert get_secret_value("SHARED", config, {}) == "first"
+
+
+def test_get_secret_value_interpolates_across_dotenv_files(tmp_path: Path):
+ first_env = tmp_path / ".env.first"
+ first_env.write_text("BASE=first", encoding="utf-8")
+ second_env = tmp_path / ".env.second"
+ second_env.write_text("API_KEY=${BASE}-key", encoding="utf-8")
+ config = MarimoConfig(
+ runtime={"dotenv": [str(first_env), str(second_env)]}
+ )
+
+ assert get_secret_value("API_KEY", config, {}) == "first-key"
+
+
+def test_get_secret_value_rereads_dotenv(tmp_path: Path):
+ env_file = tmp_path / ".env"
+ env_file.write_text("ROTATED_KEY=before", encoding="utf-8")
+ config = MarimoConfig(runtime={"dotenv": [str(env_file)]})
+
+ assert get_secret_value("ROTATED_KEY", config, {}) == "before"
+
+ env_file.write_text("ROTATED_KEY=after", encoding="utf-8")
+
+ assert get_secret_value("ROTATED_KEY", config, {}) == "after"
+
+
def test_write_secret(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
# Create a .env file
env_file = tmp_path / ".env"
diff --git a/tests/_server/ai/test_ai_config.py b/tests/_server/ai/test_ai_config.py
index b5c8996966..d52804c140 100644
--- a/tests/_server/ai/test_ai_config.py
+++ b/tests/_server/ai/test_ai_config.py
@@ -449,6 +449,29 @@ class TestAnyProviderConfig:
assert provider_config.api_key == "test-openrouter-key"
assert provider_config.base_url == "https://openrouter.ai/api/v1/"
+ def test_for_model_custom_provider_resolves_api_key_reference(
+ self,
+ ) -> None:
+ config: AiConfig = {
+ "custom_providers": {
+ "gateway": {
+ "api_key": "env:CUSTOM_API_KEY",
+ "base_url": "https://gateway.example.com/v1",
+ }
+ }
+ }
+
+ provider_config = AnyProviderConfig.for_model(
+ "gateway/custom-model",
+ config,
+ secret_resolver=lambda key: {"CUSTOM_API_KEY": "resolved-key"}.get(
+ key
+ ),
+ )
+
+ assert provider_config.api_key == "resolved-key"
+ assert provider_config.base_url == "https://gateway.example.com/v1"
+
def test_for_model_wandb(self) -> None:
"""Test for_model with Weights & Biases model."""
config: AiConfig = {"wandb": {"api_key": "test-wandb-key"}}
@@ -492,6 +515,26 @@ class TestAnyProviderConfig:
assert provider_config.api_key == "other-key"
+ def test_for_model_does_not_hide_missing_environment_reference(
+ self,
+ ) -> None:
+ config: AiConfig = {
+ "open_ai_compatible": {
+ "api_key": "env:MISSING_API_KEY",
+ "base_url": "https://gateway.example.com/v1",
+ },
+ "open_ai": {"api_key": "fallback-key"},
+ }
+
+ with pytest.raises(HTTPException) as exc_info:
+ AnyProviderConfig.for_model(
+ "provider/unknown-model",
+ config,
+ secret_resolver=lambda _key: None,
+ )
+
+ assert "'MISSING_API_KEY' is not set" in str(exc_info.value.detail)
+
@patch("marimo._server.ai.config._get_tools")
def test_tools_included_when_available(self, mock_get_tools: Any) -> None:
"""Test that tools are included when available."""
@@ -563,6 +606,18 @@ class TestProviderConfigWithFallback:
assert provider_config.api_key == "env-openai-key"
+ def test_for_openai_with_injected_fallback_key(self) -> None:
+ config: AiConfig = {"open_ai": {}}
+
+ provider_config = AnyProviderConfig.for_openai(
+ config,
+ secret_resolver=lambda key: {
+ "OPENAI_API_KEY": "dotenv-openai-key"
+ }.get(key),
+ )
+
+ assert provider_config.api_key == "dotenv-openai-key"
+
@patch.dict(os.environ, {"OPENAI_API_KEY": "env-openai-key"})
def test_for_openai_empty(self) -> None:
"""Test OpenAI config uses fallback key when config is missing api_key and config is empty."""
@@ -811,6 +866,38 @@ class TestGetKey:
assert result == "test-key"
+ def test_get_key_resolves_environment_reference(self) -> None:
+ result = _get_key(
+ {"api_key": "env:CUSTOM_API_KEY"},
+ "Test Service",
+ secret_resolver=lambda key: {"CUSTOM_API_KEY": "resolved-key"}.get(
+ key
+ ),
+ )
+
+ assert result == "resolved-key"
+
+ @pytest.mark.parametrize(
+ ("reference", "expected_detail"),
+ [
+ ("env:", "empty environment variable reference"),
+ ("env:MISSING_API_KEY", "'MISSING_API_KEY' is not set"),
+ ],
+ )
+ def test_get_key_rejects_invalid_environment_reference(
+ self, reference: str, expected_detail: str
+ ) -> None:
+ with pytest.raises(HTTPException) as exc_info:
+ _get_key(
+ {"api_key": reference},
+ "Test Service",
+ fallback_key="fallback-key",
+ secret_resolver=lambda _key: None,
+ )
+
+ assert exc_info.value.status_code == HTTPStatus.BAD_REQUEST
+ assert expected_detail in str(exc_info.value.detail)
+
def test_get_key_bedrock_profile(self):
"""Test getting Bedrock key with profile name."""
config = {"profile_name": "aws-profile"}
@@ -1278,6 +1365,19 @@ class TestSSLConfiguration:
f"{provider_name}: should use SSL_CERT_FILE env var as fallback"
)
+ @patch.dict(os.environ, {}, clear=True)
+ def test_secret_resolver_does_not_configure_ssl_cert_file(self) -> None:
+ config: AiConfig = {"open_ai": {"api_key": "test-key"}}
+
+ provider_config = AnyProviderConfig.for_openai(
+ config,
+ secret_resolver=lambda key: {
+ "SSL_CERT_FILE": "/dotenv/ca.pem"
+ }.get(key),
+ )
+
+ assert provider_config.ca_bundle_path is None
+
class TestEdgeCases:
"""Tests for edge cases and error conditions."""
diff --git a/tests/_server/api/endpoints/test_ai.py b/tests/_server/api/endpoints/test_ai.py
index 52ba389e4a..94409c68a3 100644
--- a/tests/_server/api/endpoints/test_ai.py
+++ b/tests/_server/api/endpoints/test_ai.py
@@ -6,7 +6,9 @@ from typing import TYPE_CHECKING, Any
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from starlette.exceptions import HTTPException
+from marimo._config.config import MarimoConfig
from marimo._server.ai.completion_output import (
CELL_COMPLETION_DATA_TYPE,
NOTEBOOK_CELLS_COMPLETION_DATA_TYPE,
@@ -19,12 +21,17 @@ from marimo._server.ai.prompts import (
FIM_SUFFIX_TAG,
)
from marimo._server.ai.tools.types import ToolCallResult
-from marimo._server.api.endpoints.ai import resolve_completion_messages
+from marimo._server.api.endpoints.ai import (
+ get_provider_config,
+ resolve_completion_messages,
+)
from marimo._server.models.completion import AiCompletionRequest
from tests._server.conftest import get_session_config_manager
from tests._server.mocks import token_header, with_session
if TYPE_CHECKING:
+ from pathlib import Path
+
from starlette.testclient import TestClient
SESSION_ID = "session-123"
@@ -34,6 +41,76 @@ HEADERS = {
}
+def _custom_provider_config(api_key: str, dotenvs: list[str]) -> MarimoConfig:
+ return MarimoConfig(
+ ai={
+ "models": {"chat_model": "gateway/custom-model"},
+ "custom_providers": {
+ "gateway": {
+ "api_key": api_key,
+ "base_url": "https://gateway.example.com/v1",
+ }
+ },
+ },
+ runtime={"dotenv": dotenvs},
+ )
+
+
+def test_get_provider_config_resolves_dotenv(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.delenv("CUSTOM_API_KEY", raising=False)
+ env_file = tmp_path / ".env"
+ env_file.write_text("CUSTOM_API_KEY=dotenv-key", encoding="utf-8")
+ config = _custom_provider_config("env:CUSTOM_API_KEY", [str(env_file)])
+
+ provider_config = get_provider_config("gateway/custom-model", config)
+
+ assert provider_config.api_key == "dotenv-key"
+
+
+def test_get_provider_config_prefers_environment_over_dotenv(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setenv("CUSTOM_API_KEY", "environment-key")
+ env_file = tmp_path / ".env"
+ env_file.write_text("CUSTOM_API_KEY=dotenv-key", encoding="utf-8")
+ config = _custom_provider_config("env:CUSTOM_API_KEY", [str(env_file)])
+
+ provider_config = get_provider_config("gateway/custom-model", config)
+
+ assert provider_config.api_key == "environment-key"
+
+
+def test_get_provider_config_rejects_missing_environment_reference(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("MISSING_API_KEY", raising=False)
+ config = _custom_provider_config("env:MISSING_API_KEY", [])
+
+ with pytest.raises(HTTPException) as exc_info:
+ get_provider_config("gateway/custom-model", config)
+
+ assert exc_info.value.status_code == 400
+ assert "'MISSING_API_KEY' is not set" in str(exc_info.value.detail)
+
+
+def test_get_provider_config_resolves_default_dotenv_key(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+ env_file = tmp_path / ".env"
+ env_file.write_text("OPENAI_API_KEY=dotenv-key", encoding="utf-8")
+ config = MarimoConfig(
+ ai={"open_ai": {}},
+ runtime={"dotenv": [str(env_file)]},
+ )
+
+ provider_config = get_provider_config("openai/gpt-4o", config)
+
+ assert provider_config.api_key == "dotenv-key"
+
+
# Anthropic
@dataclass
class TextDelta: