Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: send custom headers on remote connections (#15097)
Sourav Rajvi14b016639f69
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.pyindex f26c4f38d2b..4363b33970d 100644--- a/studio/backend/core/inference/external_provider.py+++ b/studio/backend/core/inference/external_provider.py@@ -34,7 +34,9 @@ from core.inference.openai_responses_shared import ()from core.inference.sse_control_frames import sanitize_provider_sse_linefrom models.providers import (+ normalize_provider_extra_headers,normalize_provider_reasoning_config,+ render_provider_extra_headers,validate_provider_reasoning_contract,)@@ -1547,6 +1549,7 @@ class ExternalProviderClient:*,api_type: str = "chat_completions",reasoning_config: Optional[dict] = None,+ extra_headers: Optional[dict] = None,managed_loopback: bool = False,):self.provider_type = provider_type@@ -1556,6 +1559,8 @@ class ExternalProviderClient:if provider_type == "custom"else None)+ self.extra_headers = normalize_provider_extra_headers(extra_headers)+ self._header_vars: dict[str, str] = {}validate_provider_reasoning_contract(provider_type, self.api_type, self.reasoning_config)from core.inference.providers import validate_provider_base_url@@ -1581,6 +1586,26 @@ class ExternalProviderClient:# same guaranteed 400 on every provider turn.self._responses_compaction_rejected = False+ def set_header_context(self, thread_id: Optional[str], model: Optional[str]) -> None:+ """Values for ``{{VAR}}`` in extra headers; set before any request of a chat turn."""+ session = (thread_id or "").strip()+ self._header_vars = {+ "CHAT_SESSION_ID": session,+ "THREAD_ID": session,+ "MODEL": model or "",+ "PROVIDER_TYPE": self.provider_type,+ }++ def _credential_digest(self) -> str:+ """Served-metadata cache identity: the key, plus the headers this request really sends."""+ material = self.api_key or ""+ headers = render_provider_extra_headers(+ getattr(self, "extra_headers", None), getattr(self, "_header_vars", None)+ )+ if headers:+ material = _json.dumps([material, headers], sort_keys = True)+ return hashlib.sha256(material.encode()).hexdigest()+def _auth_headers(self) -> dict[str, str]:"""Build authentication headers using the provider's registry config."""from core.inference.providers import get_provider_info@@ -1619,6 +1644,14 @@ class ExternalProviderClient:headers[auth_header] = f"{auth_prefix}{self.api_key}"# Merge provider-specific extra headers (anthropic-version, OpenRouter attribution).headers.update(provider_info.get("extra_headers", {}))+ custom = render_provider_extra_headers(+ getattr(self, "extra_headers", {}), getattr(self, "_header_vars", {})+ )+ if custom:+ # Header names are case-insensitive: an override replaces, never duplicates.+ overridden = {name.lower() for name in custom}+ headers = {k: v for k, v in headers.items() if k.lower() not in overridden}+ headers.update(custom)return headersdef _chat_headers(self, thread_id: Optional[str]) -> dict[str, str]:@@ -1680,6 +1713,7 @@ class ExternalProviderClient:compaction_fallback: Optional[CompactionFallback] = None,) -> AsyncGenerator[str, None]:"""tool_choice none disables all tools so they cannot bill or leak; top_k and penalties are opt-in."""+ self.set_header_context(thread_id, model)tool_choice_disabled = (isinstance(tool_choice, str) and tool_choice.strip().lower() == "none")@@ -7496,7 +7530,7 @@ class ExternalProviderClient:if self.provider_type != "vllm":return Falsenow = time.monotonic()- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest())+ key = (self.base_url, self._credential_digest())cached = _served_versions.get(key)if cached is not None and cached[0] > now:return cached[1]@@ -7525,7 +7559,7 @@ class ExternalProviderClient:if self.provider_type not in _SERVED_WINDOW_PROVIDERS:return Nonenow = time.monotonic()- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest(), model)+ key = (self.base_url, self._credential_digest(), model)cached = _served_windows.get(key)if cached is not None and cached[0] > now:return cached[1]@@ -7551,7 +7585,7 @@ class ExternalProviderClient:if self.provider_type != "llama_cpp":return Nonenow = time.monotonic()- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest(), model)+ key = (self.base_url, self._credential_digest(), model)cached = _served_templates.get(key)if cached is not None and cached[0] > now:return cached[1]diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex 037195e572e..9bc7cc97aee 100644--- a/studio/backend/models/inference.py+++ b/studio/backend/models/inference.py@@ -36,7 +36,7 @@ from core.inference.runtime_context import MAX_REQUESTABLE_CONTEXTfrom utils.upload_limits import VIDEO_INPUT_REFERENCE_JSON_MAX_BYTESfrom core.inference.video_families import MAX_VIDEO_NUM_FRAMESfrom picker.schemas import MAX_CHAT_TEMPLATE_BYTES-from models.providers import ProviderReasoningConfig+from models.providers import ProviderReasoningConfig, normalize_provider_extra_headersfrom utils.reasoning_budget import validate_reasoning_budget_message# A 24 MB reference audio as a base64 data URL, with room for its header.@@ -3272,6 +3272,22 @@ class ChatCompletionRequest(BaseModel):None,description = "[x-unsloth] Override base URL for the external provider.",)+ extra_headers: Optional[dict[str, str]] = Field(+ None,+ description = (+ "[x-unsloth] Extra request headers when the request carries an API key. "+ "Saved connections send these from the stored record instead, so an "+ "explicit key cannot bind saved metadata."+ ),+ )++ @field_validator("extra_headers", mode = "before")+ @classmethod+ def _validate_chat_extra_headers(cls, value: Any) -> Any:+ if value is None:+ return None+ return normalize_provider_extra_headers(value)+enable_prompt_caching: Optional[Union[bool, str]] = Field(None,description = (diff --git a/studio/backend/models/providers.py b/studio/backend/models/providers.pyindex c55fc6103cc..b363dec01bd 100644--- a/studio/backend/models/providers.py+++ b/studio/backend/models/providers.py@@ -3,9 +3,13 @@"""Pydantic schemas for the external LLM providers API."""+from __future__ import annotations++import refrom typing import Literal, Optional+from urllib.parse import quote-from pydantic import BaseModel, ConfigDict, Field, StrictBool, ValidationError+from pydantic import BaseModel, ConfigDict, Field, StrictBool, ValidationError, field_validatorProviderApiType = Literal["chat_completions", "responses", "systemone"]@@ -42,6 +46,78 @@ def validate_provider_reasoning_contract(provider_type: str, api_type: str, confMAX_JSON_SAFE_INTEGER = 9_007_199_254_740_991+_MAX_EXTRA_HEADERS = 16+_MAX_HEADER_NAME = 64+_MAX_HEADER_VALUE = 1024+_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")+# httpx encodes header values as ASCII; anything else fails every request to the connection.+_HEADER_VALUE_RE = re.compile(r"^[\t\x20-\x7e]*$")+_HEADER_SAFE_CHARS = "".join(chr(c) for c in range(0x20, 0x7F) if chr(c) != "%")+_HEADER_TEMPLATE_RE = re.compile(r"\{\{\s*([A-Z][A-Z0-9_]*)\s*\}\}")+_FORBIDDEN_EXTRA_HEADERS = frozenset(+ {+ "authorization",+ "proxy-authorization",+ "cookie",+ "set-cookie",+ "host",+ "content-length",+ "content-type",+ "connection",+ "transfer-encoding",+ "te",+ "trailer",+ "upgrade",+ "keep-alive",+ "api-key",+ "x-api-key",+ "x-goog-api-key",+ }+)+++def normalize_provider_extra_headers(value) -> dict[str, str]:+ """Validate a connection's extra headers. Empty or absent becomes {}."""+ if value is None:+ return {}+ if not isinstance(value, dict):+ raise ValueError("extra_headers must be an object of header name to value.")+ if len(value) > _MAX_EXTRA_HEADERS:+ raise ValueError(f"At most {_MAX_EXTRA_HEADERS} extra headers are allowed.")+ headers: dict[str, str] = {}+ for raw_name, raw_value in value.items():+ if not isinstance(raw_name, str) or not isinstance(raw_value, str):+ raise ValueError("extra_headers keys and values must be strings.")+ name = raw_name.strip()+ if not name or len(name) > _MAX_HEADER_NAME or not _HEADER_NAME_RE.fullmatch(name):+ raise ValueError(f"Invalid extra header name: {raw_name!r}.")+ if name.lower() in _FORBIDDEN_EXTRA_HEADERS:+ raise ValueError(f"Cannot set reserved header {name!r}.")+ if not _HEADER_VALUE_RE.fullmatch(raw_value):+ raise ValueError(f"Header {name!r} must be printable ASCII on one line.")+ if len(raw_value) > _MAX_HEADER_VALUE:+ raise ValueError(f"Header {name!r} is too long.")+ # h11 refuses a value with surrounding whitespace.+ headers[name] = raw_value.strip(" \t")+ return headers+++def render_provider_extra_headers(+ headers: dict[str, str] | None, variables: dict[str, str] | None = None+) -> dict[str, str]:+ """Replace ``{{ VAR }}`` placeholders. Unknown names become empty strings."""+ if not headers:+ return {}+ values = variables or {}++ def replace(match: re.Match[str]) -> str:+ # Substituted ids and model names are arbitrary text; percent-encode what httpx cannot send.+ return quote(values.get(match.group(1), ""), safe = _HEADER_SAFE_CHARS)++ return {+ name: _HEADER_TEMPLATE_RE.sub(replace, value).strip(" \t")+ for name, value in headers.items()+ }class ProviderRegistryEntry(BaseModel):@@ -82,7 +158,21 @@ class ProviderRegistryEntry(BaseModel):)-class ProviderCreate(BaseModel):+class ExtraHeadersMixin(BaseModel):+ extra_headers: Optional[dict[str, str]] = Field(+ default = None,+ description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",+ )++ @field_validator("extra_headers", mode = "before")+ @classmethod+ def _validate_extra_headers(cls, value):+ if value is None:+ return None+ return normalize_provider_extra_headers(value)+++class ProviderCreate(ExtraHeadersMixin):"""Request to create a saved provider configuration."""api_type: ProviderApiType = "chat_completions"@@ -120,7 +210,7 @@ class ProviderCreate(BaseModel):)-class ProviderUpdate(BaseModel):+class ProviderUpdate(ExtraHeadersMixin):"""Request to update a saved provider configuration."""api_type: Optional[ProviderApiType] = None@@ -194,6 +284,10 @@ class ProviderResponse(BaseModel):None,description = "Configured maximum Max Tokens cap for this connection",)+ extra_headers: dict[str, str] = Field(+ default_factory = dict,+ description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",+ )shared: bool = Field(False, description = "Whether every account on this installation can use it")shared_by_owner: bool = Field(False,@@ -236,7 +330,7 @@ class ModelCatalogResponse(BaseModel):providers: dict[str, dict[str, dict]]-class ProviderModelsRequest(BaseModel):+class ProviderModelsRequest(ExtraHeadersMixin):"""Request to list models from an external provider."""api_type: ProviderApiType = "chat_completions"@@ -255,7 +349,7 @@ class ProviderModelsRequest(BaseModel):)-class ProviderTestRequest(BaseModel):+class ProviderTestRequest(ExtraHeadersMixin):"""Request to test connectivity to an external provider."""api_type: ProviderApiType = "chat_completions"diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex 86d867c306f..ab87d7db58e 100644--- a/studio/backend/routes/inference.py+++ b/studio/backend/routes/inference.py@@ -3604,6 +3604,18 @@ def _request_is_saved_credential_workflow(request: Any) -> bool:# A UI session, the Deep Research key, or the key `unsloth start` minted for the owner's coding# agents. Every other API key, keyless caller and data-recipe key still gets nothing.+def _saved_extra_headers(row: Optional[dict], request: Any) -> dict:+ """A saved row's headers, under the same API-key gate as its saved key."""+ if not row or _request_has_api_key(request):+ return {}+ return row.get("extra_headers") or {}+++def _saved_extra_headers_kwarg(row: Optional[dict], request: Any) -> dict:+ headers = _saved_extra_headers(row, request)+ return {"extra_headers": headers} if headers else {}++def _request_may_use_saved_provider_key(request: Any) -> bool:if not _request_has_api_key(request) or _request_is_saved_credential_workflow(request):return True@@ -24463,6 +24475,7 @@ async def _external_tts_speech(body: AudioSpeechRequest, request: Request) -> Reprovider_type = config["provider_type"],base_url = base_url,api_key = api_key,+ **_saved_extra_headers_kwarg(current, request),)# FastAPI does not cancel non-streaming handlers on disconnect; paid synthesis would continue.speech_task = asyncio.create_task(@@ -24746,6 +24759,7 @@ async def _external_stt_transcription(provider_type = config["provider_type"],base_url = base_url,api_key = api_key,+ **_saved_extra_headers_kwarg(current, request),)transcription_task = asyncio.create_task(client.create_transcription(@@ -28535,6 +28549,7 @@ async def _proxy_to_external_provider(base_url = payload.provider_base_urlapi_type = payload.provider_api_typereasoning_config = normalize_provider_reasoning_config(payload.provider_reasoning_config)+ extra_headers: Optional[dict] = Nonesaved_provider_snapshot: Optional[dict] = Noneif managed is not None:@@ -28566,6 +28581,11 @@ async def _proxy_to_external_provider(base_url = config["base_url"]api_type = config.get("api_type", "chat_completions")reasoning_config = normalize_provider_reasoning_config(config.get("reasoning_config"))+ extra_headers = config.get("extra_headers")++ # An explicit key keeps the edited target: headers come from the request, not the saved row.+ if managed is None and payload.encrypted_api_key:+ extra_headers = payload.extra_headersif not provider_type:raise HTTPException(@@ -29081,12 +29101,16 @@ async def _proxy_to_external_provider(account_access.require_connection_model_allowed(current, payload.external_model or payload.model)+ may_use_saved = _request_may_use_saved_provider_key(request)api_key = await asyncio.to_thread(resolve_provider_api_key_or_400,payload.provider_id,payload.encrypted_api_key,- allow_saved_key = _request_may_use_saved_provider_key(request),+ allow_saved_key = may_use_saved,)+ if not payload.encrypted_api_key:+ # Saved headers can carry credentials: same gate as the saved key.+ extra_headers = current.get("extra_headers") if may_use_saved else Noneelse:api_key = resolve_provider_api_key_or_400(payload.provider_id,@@ -29145,8 +29169,12 @@ async def _proxy_to_external_provider(api_key = api_key,api_type = api_type,**({"reasoning_config": reasoning_config} if reasoning_config is not None else {}),+ **({"extra_headers": extra_headers} if extra_headers else {}),**({"managed_loopback": True} if managed is not None else {}),)+ # Metadata preflights (served context window, template) run before streaming starts.+ if extra_headers:+ client.set_header_context(payload.thread_id, model)_non_stream_custom_responses = (provider_type == "custom" and api_type == "responses" and payload.stream is False)@@ -29998,7 +30026,9 @@ def _resolve_openai_cloud_client() -> ExternalProviderClient:"""Needs an OpenAI cloud base URL (shell tool exists only there); runs on the loop for one snapshot."""base_url = body.provider_base_url or get_base_url("openai")- if body.provider_id and not body.encrypted_api_key:+ config: dict = {}+ saved_config = bool(body.provider_id and not body.encrypted_api_key)+ if saved_config:config = providers_db.get_provider(body.provider_id)if config is None:raise HTTPException(@@ -30041,10 +30071,13 @@ def _resolve_openai_cloud_client()if not api_key:raise HTTPException(status_code = 400, detail = "No OpenAI API key is saved.")+ # Same project / organization scope as chat on this connection.+ headers = config.get("extra_headers") if saved_config and allow_saved_key else Nonereturn ExternalProviderClient(provider_type = "openai",base_url = base_url,api_key = api_key,+ **({"extra_headers": headers} if headers else {}),)@@ -49138,6 +49171,7 @@ async def _external_image_generation(provider_type = config["provider_type"],base_url = base_url,api_key = api_key,+ **_saved_extra_headers_kwarg(current, request),timeout = 600.0,)owner = current_account_id()diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.pyindex 46b5553c729..cfac166b826 100644--- a/studio/backend/routes/providers.py+++ b/studio/backend/routes/providers.py@@ -63,6 +63,7 @@ from models.providers import (ProviderTestRequest,ProviderTestResult,ProviderUpdate,+ normalize_provider_extra_headers,validate_provider_reasoning_contract,)from storage import credential_secrets, providers_db@@ -143,7 +144,21 @@ def _log_provider_failure(event: str, exc: Exception, **fields) -> None:_SHARED_READ_ONLY = "This connection is shared by the installation owner. Only they can change it."-def _provider_response(row: dict) -> ProviderResponse:+def _request_extra_headers(payload, via_api_key: bool) -> dict[str, str]:+ if "extra_headers" in getattr(payload, "model_fields_set", set()):+ return normalize_provider_extra_headers(payload.extra_headers)+ provider_id = getattr(payload, "provider_id", None)+ # Saved headers can carry credentials: same gate as the saved key.+ if not provider_id or payload.encrypted_api_key or via_api_key:+ return {}+ row = providers_db.get_provider(provider_id)+ # Saved headers go only to the saved endpoint, like the saved key.+ if not row or (payload.base_url or None) != (row.get("base_url") or None):+ return {}+ return normalize_provider_extra_headers(row.get("extra_headers"))+++def _provider_response(row: dict, *, hide_headers: bool = False) -> ProviderResponse:has_api_key = credential_secrets.provider_api_key_saved(row["id"])return ProviderResponse(id = row["id"],@@ -152,6 +167,12 @@ def _provider_response(row: dict) -> ProviderResponse:base_url = row["base_url"],api_type = row.get("api_type", "chat_completions"),reasoning_config = row.get("reasoning_config"),+ # Header values can carry credentials; other accounts and API keys never read them.+ extra_headers = (+ {}+ if hide_headers or row.get("shared_by_owner")+ else normalize_provider_extra_headers(row.get("extra_headers"))+ ),is_enabled = bool(row["is_enabled"]),has_api_key = has_api_key,auth_kind = ("chatgpt_oauth" if row["provider_type"] == "openai_codex" else "api_key"),@@ -298,10 +319,13 @@ async def get_pricing_snapshot(current_subject: str = Depends(get_current_subjec# FastAPI offloads sync reads; mutations stay on-loop to preserve atomic sequences.@router.get("/", response_model = list[ProviderResponse])-def list_provider_configs(_current_subject: str = Depends(get_current_subject)):+def list_provider_configs(+ _current_subject: str = Depends(get_current_subject),+ via_api_key: bool = Depends(authenticated_via_api_key),+):"""List all saved provider configurations."""rows = providers_db.list_providers()- return [_provider_response(row) for row in rows]+ return [_provider_response(row, hide_headers = via_api_key) for row in rows]@router.post("/", response_model = ProviderResponse, status_code = 201)@@ -368,6 +392,7 @@ async def create_provider_config(max_output_tokens = payload.max_output_tokens,api_type = payload.api_type,reasoning_config = payload.reasoning_config,+ extra_headers = payload.extra_headers,shared = payload.shared,)try:@@ -472,6 +497,7 @@ async def update_provider_config("max_output_tokens","api_type","reasoning_config",+ "extra_headers","shared",}metadata_requested = bool(payload.model_fields_set & metadata_fields)@@ -513,6 +539,8 @@ async def update_provider_config(if payload.reasoning_config is not Noneelse None)+ if "extra_headers" in payload.model_fields_set:+ metadata_updates["extra_headers"] = payload.extra_headers or {}# The row snapshot this request found, keyed the way update_provider takes it._restorable = dict(@@ -524,6 +552,7 @@ async def update_provider_config(max_output_tokens = existing.get("max_output_tokens"),api_type = existing.get("api_type", "chat_completions"),reasoning_config = existing.get("reasoning_config"),+ extra_headers = existing.get("extra_headers") or {},shared = bool(existing.get("shared")),)@@ -545,7 +574,11 @@ async def update_provider_config(if field == "id":continue# Explicit null clears nullable overrides; elsewhere it means "not sent".- if written is None and field not in {"max_output_tokens", "reasoning_config"}:+ if written is None and field not in {+ "max_output_tokens",+ "reasoning_config",+ "extra_headers",+ }:continueif not _current_matches(current, field, written):continue@@ -976,6 +1009,7 @@ async def test_provider(base_url = base_url,api_key = api_key,api_type = payload.api_type,+ extra_headers = _request_extra_headers(payload, via_api_key),timeout = _PROVIDER_CONNECTIVITY_TIMEOUT_SECONDS,)@@ -1157,7 +1191,10 @@ async def _list_model_capabilities(payload: ProviderModelsRequest, via_api_key:raise HTTPException(status_code = 400, detail = str(exc)) from None# Per credential: one key's model list is not another caller's.- key_digest = hashlib.sha256((api_key or "").encode("utf-8")).hexdigest()[:16]+ extra_headers = _request_extra_headers(payload, via_api_key)+ key_digest = hashlib.sha256(+ json.dumps([api_key or "", extra_headers], sort_keys = True).encode("utf-8")+ ).hexdigest()[:16]cache_key = f"{payload.provider_type}\n{base_url}\n{key_digest}"cached = _model_capability_cache.get(cache_key)if cached is not None and time.monotonic() - cached[0] < _MODEL_CAPABILITY_CACHE_TTL_SECONDS:@@ -1169,6 +1206,7 @@ async def _list_model_capabilities(payload: ProviderModelsRequest, via_api_key:base_url = base_url,api_key = api_key,api_type = payload.api_type,+ extra_headers = extra_headers,timeout = 15.0,)try:@@ -1255,6 +1293,7 @@ async def list_provider_models(base_url = base_url,api_key = api_key,api_type = payload.api_type,+ extra_headers = _request_extra_headers(payload, via_api_key),timeout = 15.0,)diff --git a/studio/backend/routes/systemone.py b/studio/backend/routes/systemone.pyindex 5e481671b15..aa795aef175 100644--- a/studio/backend/routes/systemone.py+++ b/studio/backend/routes/systemone.py@@ -364,7 +364,13 @@ async def _connection_decide(except ValueError as exc:raise _error(503, "api_usage_error", str(exc)) from Noneapi_key = await arun_as(OWNER, _connection_key(provider_id, config))- client = ExternalProviderClient(config["provider_type"], base_url, api_key)+ headers = config.get("extra_headers")+ client = ExternalProviderClient(+ config["provider_type"],+ base_url,+ api_key,+ **({"extra_headers": headers} if headers else {}),+ )try:result = await client.create_decision(connection.model, state, questions)except httpx.HTTPStatusError as exc:@@ -381,7 +387,7 @@ async def _connection_decide(async def _connection_key(provider_id: str, config: dict) -> str:- routing_fields = ("provider_type", "base_url", "api_type", "is_enabled")+ routing_fields = ("provider_type", "base_url", "api_type", "is_enabled", "extra_headers")async with provider_config_guard(provider_id):current = await asyncio.to_thread(providers_db.get_provider, provider_id)if current is None or any(current.get(f) != config.get(f) for f in routing_fields):@@ -416,7 +422,13 @@ async def refresh_listed_decision_models() -> None:None,prefer_saved_key = True,)- client = ExternalProviderClient(row["provider_type"], row["base_url"], api_key, 10.0)+ client = ExternalProviderClient(+ row["provider_type"],+ row["base_url"],+ api_key,+ 10.0,+ **({"extra_headers": row["extra_headers"]} if row.get("extra_headers") else {}),+ )models = await arun_as(OWNER, client.list_decision_models())except Exception:models = []diff --git a/studio/backend/storage/providers_db.py b/studio/backend/storage/providers_db.pyindex 02d66ede406..91de70dec35 100644--- a/studio/backend/storage/providers_db.py+++ b/studio/backend/storage/providers_db.py@@ -18,7 +18,11 @@ from urllib.parse import urlparselogger = logging.getLogger(__name__)-from models.providers import ProviderReasoningConfig, normalize_provider_reasoning_config+from models.providers import (+ ProviderReasoningConfig,+ normalize_provider_extra_headers,+ normalize_provider_reasoning_config,+)from storage.studio_db import connect_studio_dbfrom utils.paths import studio_db_path, ensure_dir@@ -100,6 +104,22 @@ def _decode_reasoning_config(raw) -> Optional[dict]:return None+def _encode_extra_headers(headers) -> Optional[str]:+ normalized = normalize_provider_extra_headers(headers)+ if not normalized:+ return None+ return json.dumps(normalized)+++def _decode_extra_headers(raw) -> dict[str, str]:+ if not raw:+ return {}+ try:+ return normalize_provider_extra_headers(json.loads(raw))+ except (json.JSONDecodeError, TypeError, ValueError):+ return {}++def _row_models(row: sqlite3.Row) -> tuple[list[str], list[str]]:return (_decode_models_json(row["models_json"] if "models_json" in row.keys() else None),@@ -141,6 +161,8 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:conn.execute("ALTER TABLE llm_providers ADD COLUMN max_output_tokens INTEGER")if "reasoning_config_json" not in existing_cols:conn.execute("ALTER TABLE llm_providers ADD COLUMN reasoning_config_json TEXT")+ if "extra_headers_json" not in existing_cols:+ conn.execute("ALTER TABLE llm_providers ADD COLUMN extra_headers_json TEXT")if "shared" not in existing_cols:conn.execute("ALTER TABLE llm_providers ADD COLUMN shared INTEGER NOT NULL DEFAULT 0")# ALTER TABLE persists independently in SQLite, but its one-time data migration does not.@@ -201,10 +223,12 @@ def create_provider(max_output_tokens: Optional[int] = None,api_type: str = "chat_completions",reasoning_config: Optional[dict] = None,+ extra_headers: Optional[dict] = None,shared: bool = False,) -> None:"""Insert a new provider configuration."""reasoning_json = _encode_reasoning_config(reasoning_config)+ extra_headers_json = _encode_extra_headers(extra_headers)now = datetime.now(timezone.utc).isoformat()conn = get_connection()try:@@ -213,9 +237,9 @@ def create_provider(INSERT INTO llm_providers (id, provider_type, display_name, base_url,models_json, available_models_json, max_output_tokens, api_type,- reasoning_config_json, shared, created_at, updated_at+ reasoning_config_json, extra_headers_json, shared, created_at, updated_at)- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",(id,@@ -227,6 +251,7 @@ def create_provider(max_output_tokens,api_type,reasoning_json,+ extra_headers_json,1 if shared else 0,now,now,@@ -249,6 +274,7 @@ def update_provider(connection: sqlite3.Connection | None = None,api_type: str | None = None,reasoning_config: dict | None | object = _UNSET,+ extra_headers: dict | None | object = _UNSET,shared: bool | None = None,) -> bool:"""Update fields on an existing provider. Returns True if a row was updated."""@@ -278,6 +304,9 @@ def update_provider(if reasoning_config is not _UNSET:updates.append("reasoning_config_json = ?")params.append(_encode_reasoning_config(reasoning_config))+ if extra_headers is not _UNSET:+ updates.append("extra_headers_json = ?")+ params.append(_encode_extra_headers(extra_headers))if shared is not None:updates.append("shared = ?")params.append(1 if shared else 0)@@ -316,6 +345,7 @@ def delete_provider(id: str) -> bool:def _row_to_provider(row: sqlite3.Row) -> dict:data = dict(row)data["reasoning_config"] = _decode_reasoning_config(data.pop("reasoning_config_json", None))+ data["extra_headers"] = _decode_extra_headers(data.pop("extra_headers_json", None))models, available_models = _row_models(row)data["models"] = modelsdata["available_models"] = available_modelsdiff --git a/studio/backend/tests/test_account_shared_connections.py b/studio/backend/tests/test_account_shared_connections.pyindex 2ab94fbc137..c062d5973db 100644--- a/studio/backend/tests/test_account_shared_connections.py+++ b/studio/backend/tests/test_account_shared_connections.py@@ -434,3 +434,125 @@ def test_checking_a_shared_connection_probes_no_model_and_quotes_no_upstream_err"message": "Connection failed. Ask the owner to check this connection.","models_count": None,}+++def header_upstream():+ seen = []++ class Handler(http.server.BaseHTTPRequestHandler):+ def do_GET(self):+ seen.append(self.headers.get("X-Gateway-Token"))+ body = json.dumps({"data": [{"id": model} for model in UPSTREAM_MODELS]}).encode()+ self.send_response(200)+ self.send_header("Content-Type", "application/json")+ self.send_header("Content-Length", str(len(body)))+ self.end_headers()+ self.wfile.write(body)++ def log_message(self, *args):+ pass++ server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ threading.Thread(target = server.serve_forever, daemon = True).start()+ try:+ yield f"http://127.0.0.1:{server.server_address[1]}/v1", seen+ finally:+ server.shutdown()+ server.server_close()+++def test_shared_extra_headers_stay_with_the_saved_endpoint(monkeypatch, header_upstream):+ base_url, seen = header_upstream+ provider_id = owner_connection("https://api.example.com/v1")+ run_as(+ OWNER,+ providers_db.update_provider,+ provider_id,+ extra_headers = {"X-Gateway-Token": "owner-header-secret"},+ )+ mpu.set_managed_private_provider_urls_allowed(True)+ [row] = listed(ALICE)+ assert "owner-header-secret" not in json.dumps(row)+ [owner_row] = listed(OWNER)+ assert owner_row["extra_headers"] == {"X-Gateway-Token": "owner-header-secret"}++ monkeypatch.setattr(providers, "resolve_provider_api_key_or_400", lambda *a, **k: "alice-key")+ with client_for(ALICE) as client:+ response = client.post(+ "/providers/models",+ json = {+ "provider_type": "custom",+ "provider_id": provider_id,+ "encrypted_api_key": "alice-encrypted",+ "base_url": base_url,+ },+ )+ assert response.status_code == 200, response.text+ assert seen == [None]+++def api_key_client_for(account):+ client = client_for(account)+ client.app.dependency_overrides[authenticated_via_api_key] = lambda: True+ return client+++def test_api_key_callers_neither_read_nor_spend_saved_headers(monkeypatch, header_upstream):+ base_url, seen = header_upstream+ mpu.set_managed_private_provider_urls_allowed(True)+ with client_for(OWNER) as client:+ created = client.post(+ "/providers/",+ json = {+ "provider_type": "custom",+ "display_name": "Header Gateway",+ "base_url": base_url,+ "models": UPSTREAM_MODELS[:1],+ "extra_headers": {"X-Gateway-Token": "owner-header-secret"},+ },+ )+ assert created.status_code == 201, created.text+ provider_id = created.json()["id"]+ with api_key_client_for(OWNER) as client:+ [row] = client.get("/providers/").json()+ assert "owner-header-secret" not in json.dumps(row)+ response = client.post(+ "/providers/models", json = {"provider_type": "custom", "provider_id": provider_id}+ )+ assert response.status_code == 200, response.text+ with client_for(OWNER) as client:+ response = client.post(+ "/providers/models", json = {"provider_type": "custom", "provider_id": provider_id}+ )+ assert response.status_code == 200, response.text+ assert seen == [None, "owner-header-secret"]+++def test_capability_cache_is_keyed_by_headers(monkeypatch):+ calls = []++ class FakeClient:+ def __init__(self, **kwargs):+ calls.append(kwargs["extra_headers"])++ async def list_models(self):+ return [{"id": "m"}]++ async def close(self):+ pass++ monkeypatch.setattr(providers, "ExternalProviderClient", FakeClient)+ monkeypatch.setattr(providers, "resolve_provider_api_key_or_400", lambda *a, **k: "shared-key")+ monkeypatch.setattr(providers, "validate_provider_base_url", lambda url: url)+ providers._model_capability_cache.clear()+ from models.providers import ProviderModelsRequest++ for tenant in ("a", "b", "a"):+ payload = ProviderModelsRequest(+ provider_type = "openrouter",+ base_url = "https://gw.example/v1",+ extra_headers = {"X-Tenant": tenant},+ )+ asyncio.run(providers._list_model_capabilities(payload, False))+ assert calls == [{"X-Tenant": "a"}, {"X-Tenant": "b"}]diff --git a/studio/backend/tests/test_provider_extra_headers.py b/studio/backend/tests/test_provider_extra_headers.pynew file mode 100644index 00000000000..02568023f8b--- /dev/null+++ b/studio/backend/tests/test_provider_extra_headers.py@@ -0,0 +1,339 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Saved connection extra headers, including {{CHAT_SESSION_ID}} interpolation."""++import asyncio+import json+from http.server import BaseHTTPRequestHandler+from types import SimpleNamespace++import httpx+import pytest+from pydantic import ValidationError++from core.inference import external_provider as ep+from models.providers import (+ ProviderCreate,+ ProviderUpdate,+ normalize_provider_extra_headers,+ render_provider_extra_headers,+)+from storage import providers_db+from .test_external_provider_sampling_over_the_wire import _Server+++HEADERS = {"X-LiteLLM-Session-Id": "unsloth-{{CHAT_SESSION_ID}}", "X-Title": "Unsloth"}+++class Handler(BaseHTTPRequestHandler):+ def log_message(self, *args):+ pass++ def do_POST(self): # noqa: N802+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))+ self.server.recorded.append(+ {+ "path": self.path,+ "body": body,+ "session": self.headers.get("X-LiteLLM-Session-Id"),+ "title": self.headers.get("X-Title"),+ "authorization": self.headers.get("Authorization"),+ }+ )+ data = b'data: {"choices":[{"index":0,"delta":{"content":"ok"}}]}\n\ndata: [DONE]\n\n'+ self.send_response(200)+ self.send_header("Content-Type", "text/event-stream")+ self.send_header("Content-Length", str(len(data)))+ self.end_headers()+ self.wfile.write(data)+++def test_reserved_headers_are_rejected():+ with pytest.raises(ValueError, match = "reserved"):+ normalize_provider_extra_headers({"Authorization": "Bearer secret"})+ with pytest.raises(ValidationError):+ ProviderCreate(+ provider_type = "custom",+ display_name = "Gateway",+ extra_headers = {"Authorization": "Bearer secret"},+ )+++def test_header_values_must_be_sendable():+ for value in ("Ünsloth", "a\nb", "a\x00b"):+ with pytest.raises(ValueError, match = "printable ASCII"):+ normalize_provider_extra_headers({"X-Title": value})+ assert normalize_provider_extra_headers({"X-Title": "a\tb c"}) == {"X-Title": "a\tb c"}+++def test_template_interpolation():+ rendered = render_provider_extra_headers(+ HEADERS, {"CHAT_SESSION_ID": "thread-1", "MODEL": "gpt"}+ )+ assert rendered["X-LiteLLM-Session-Id"] == "unsloth-thread-1"+ assert rendered["X-Title"] == "Unsloth"+++def test_extra_headers_persist_and_reach_the_wire(tmp_path, monkeypatch):+ monkeypatch.setattr(providers_db, "studio_db_path", lambda: tmp_path / "studio.db")+ providers_db.reset_schema_state_for_tests()+ payload = ProviderCreate(+ provider_type = "custom",+ display_name = "LiteLLM",+ base_url = "https://gateway.example/v1",+ extra_headers = HEADERS,+ )+ providers_db.create_provider(id = "litellm", **payload.model_dump(exclude = {"encrypted_api_key"}))+ row = providers_db.get_provider("litellm")+ assert row["extra_headers"] == HEADERS+ assert providers_db.update_provider("litellm", extra_headers = {"X-Title": "Studio"})+ assert providers_db.get_provider("litellm")["extra_headers"] == {"X-Title": "Studio"}+ assert ProviderUpdate(extra_headers = None).extra_headers is None++ with _Server(Handler) as server:++ async def send():+ async with httpx.AsyncClient(trust_env = False) as transport:+ monkeypatch.setattr(ep, "_http_client", transport)+ client = ep.ExternalProviderClient(+ "custom",+ server.base_url,+ "sk-test",+ extra_headers = HEADERS,+ )+ output = client.stream_chat_completion(+ messages = [{"role": "user", "content": "hi"}],+ model = "proxy-model",+ thread_id = "chat-42",+ )+ assert "ok" in "".join([line async for line in output])+ await client.close()++ asyncio.run(send())+ recorded = server.bodies[-1]+ assert recorded["session"] == "unsloth-chat-42"+ assert recorded["title"] == "Unsloth"+ assert recorded["authorization"] == "Bearer sk-test"+++def _drive(coro):+ return asyncio.new_event_loop().run_until_complete(coro)+++def test_explicit_key_sends_request_headers_without_saved_lookup(monkeypatch):+ from models.inference import ChatCompletionRequest+ from routes import inference as inf_mod++ class ClientReached(Exception):+ pass++ monkeypatch.setattr(+ inf_mod.providers_db,+ "get_provider",+ lambda _provider_id: (_ for _ in ()).throw(+ AssertionError("explicit keys must not bind saved metadata")+ ),+ )+ monkeypatch.setattr(+ inf_mod,+ "resolve_provider_api_key_or_400",+ lambda *_args, **_kwargs: "replacement-key",+ )++ def client(**kwargs):+ raise ClientReached(kwargs)++ monkeypatch.setattr(inf_mod, "ExternalProviderClient", client)+ payload = ChatCompletionRequest(+ messages = [{"role": "user", "content": "hello"}],+ provider_id = "provider-1",+ provider_type = "custom",+ provider_base_url = "https://new.example/v1",+ encrypted_api_key = "encrypted-replacement",+ extra_headers = HEADERS,+ external_model = "new-model",+ )+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))+ with pytest.raises(ClientReached) as reached:+ _drive(inf_mod._proxy_to_external_provider(payload, request))+ assert reached.value.args[0] == {+ "provider_type": "custom",+ "base_url": "https://new.example/v1",+ "api_key": "replacement-key",+ "api_type": "chat_completions",+ "extra_headers": HEADERS,+ }+++def test_chat_request_rejects_reserved_extra_headers():+ from models.inference import ChatCompletionRequest+ with pytest.raises(ValidationError, match = "reserved"):+ ChatCompletionRequest(+ messages = [{"role": "user", "content": "hello"}],+ extra_headers = {"Authorization": "Bearer secret"},+ )++[email protected]("may_use_saved", [True, False])+def test_saved_headers_follow_the_saved_key_gate(monkeypatch, may_use_saved):+ from models.inference import ChatCompletionRequest+ from routes import inference as inf_mod++ class ClientReached(Exception):+ pass++ row = {+ "id": "provider-1",+ "provider_type": "custom",+ "display_name": "Gateway",+ "base_url": "https://gw.example/v1",+ "api_type": "chat_completions",+ "is_enabled": True,+ "reasoning_config": None,+ "extra_headers": {"X-Gateway-Token": "saved-secret"},+ }+ monkeypatch.setattr(inf_mod.providers_db, "get_provider", lambda _pid: dict(row))+ monkeypatch.setattr(inf_mod, "_request_may_use_saved_provider_key", lambda _r: may_use_saved)+ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: None)++ def client(**kwargs):+ raise ClientReached(kwargs)++ monkeypatch.setattr(inf_mod, "ExternalProviderClient", client)+ payload = ChatCompletionRequest(+ messages = [{"role": "user", "content": "hello"}],+ provider_id = "provider-1",+ external_model = "m",+ )+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))+ with pytest.raises(ClientReached) as reached:+ _drive(inf_mod._proxy_to_external_provider(payload, request))+ sent = reached.value.args[0].get("extra_headers")+ assert sent == ({"X-Gateway-Token": "saved-secret"} if may_use_saved else None)+++def test_saved_extra_headers_helper_honours_api_keys(monkeypatch):+ from routes import inference as inf_mod++ row = {"extra_headers": {"X-Gateway-Token": "saved-secret"}}+ monkeypatch.setattr(inf_mod, "_request_has_api_key", lambda _r: False)+ assert inf_mod._saved_extra_headers(row, object()) == row["extra_headers"]+ monkeypatch.setattr(inf_mod, "_request_has_api_key", lambda _r: True)+ assert inf_mod._saved_extra_headers(row, object()) == {}+++def test_values_are_trimmed_and_substitutions_stay_sendable():+ assert normalize_provider_extra_headers({"X-Token": " secret "}) == {"X-Token": "secret"}+ rendered = render_provider_extra_headers(+ {"X-Session": "unsloth-{{CHAT_SESSION_ID}}", "X-Model": "{{MODEL}} "},+ {"CHAT_SESSION_ID": "会話-1\r\n", "MODEL": ""},+ )+ assert rendered == {"X-Session": "unsloth-%E4%BC%9A%E8%A9%B1-1%0D%0A", "X-Model": ""}+ httpx.Request("GET", "http://x", headers = rendered)++[email protected]("allow_saved_key", [True, False])+def test_container_client_keeps_the_connection_scope(monkeypatch, allow_saved_key):+ from models.inference import OpenAIContainerRequest+ from routes import inference as inf_mod++ row = {+ "id": "openai-1",+ "provider_type": "openai",+ "display_name": "OpenAI",+ "base_url": "https://api.openai.com/v1",+ "is_enabled": True,+ "extra_headers": {"OpenAI-Project": "proj_123"},+ }+ monkeypatch.setattr(inf_mod.providers_db, "get_provider", lambda _pid: dict(row))+ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: "sk-test")+ captured = {}+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", lambda **kw: captured.update(kw))+ inf_mod._resolve_openai_cloud_client(+ OpenAIContainerRequest(provider_id = "openai-1"), allow_saved_key = allow_saved_key+ )+ assert captured.get("extra_headers") == (+ {"OpenAI-Project": "proj_123"} if allow_saved_key else None+ )+++def test_served_metadata_cache_identity_includes_headers():+ import hashlib++ plain = ep.ExternalProviderClient("custom", "https://gw.example/v1", "sk")+ assert plain._credential_digest() == hashlib.sha256(b"sk").hexdigest()+ a = ep.ExternalProviderClient(+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Tenant": "a"}+ )+ b = ep.ExternalProviderClient(+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Tenant": "b"}+ )+ assert len({plain._credential_digest(), a._credential_digest(), b._credential_digest()}) == 3+ routed = ep.ExternalProviderClient(+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Route": "{{CHAT_SESSION_ID}}"}+ )+ routed.set_header_context("chat-1", "m")+ first = routed._credential_digest()+ routed.set_header_context("chat-2", "m")+ assert routed._credential_digest() != first+++def test_extra_headers_replace_registry_headers_case_insensitively():+ client = ep.ExternalProviderClient(+ "openrouter", "https://openrouter.ai/api/v1", "sk", extra_headers = {"x-title": "My App"}+ )+ headers = client._auth_headers()+ assert [k for k in headers if k.lower() == "x-title"] == ["x-title"]+ assert headers["x-title"] == "My App"+++def test_route_sets_header_context_before_any_upstream_call(monkeypatch):+ from models.inference import ChatCompletionRequest+ from routes import inference as inf_mod++ class ContextSet(Exception):+ pass++ class FakeClient:+ def __init__(self, **kwargs):+ self.kwargs = kwargs++ def set_header_context(self, thread_id, model):+ raise ContextSet(thread_id, model)++ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: "key")+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", FakeClient)+ payload = ChatCompletionRequest(+ messages = [{"role": "user", "content": "hello"}],+ provider_type = "custom",+ provider_base_url = "https://gw.example/v1",+ encrypted_api_key = "encrypted",+ extra_headers = HEADERS,+ external_model = "m",+ thread_id = "chat-7",+ )+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))+ with pytest.raises(ContextSet) as reached:+ _drive(inf_mod._proxy_to_external_provider(payload, request))+ assert reached.value.args == ("chat-7", "m")+++def test_decision_key_refuses_headers_changed_mid_start(monkeypatch):+ from fastapi import HTTPException+ from routes import systemone++ row = {+ "provider_type": "custom",+ "base_url": "https://gw.example/v1",+ "api_type": "systemone",+ "is_enabled": True,+ "extra_headers": {"X-Gateway-Token": "new"},+ }+ monkeypatch.setattr(systemone.providers_db, "get_provider", lambda _pid: dict(row))+ monkeypatch.setattr(systemone, "resolve_provider_api_key_or_400", lambda *a, **k: "new-key")+ stale = {**row, "extra_headers": {"X-Gateway-Token": "old"}}+ with pytest.raises(HTTPException) as refused:+ _drive(systemone._connection_key("p", stale))+ assert refused.value.status_code == 409+ assert _drive(systemone._connection_key("p", dict(row))) == "new-key"diff --git a/studio/frontend/src/features/chat/api/providers-api.ts b/studio/frontend/src/features/chat/api/providers-api.tsindex 44c04c38d99..8146888506f 100644--- a/studio/frontend/src/features/chat/api/providers-api.ts+++ b/studio/frontend/src/features/chat/api/providers-api.ts@@ -55,6 +55,7 @@ export interface ProviderConfig {available_models?: string[];max_output_tokens?: number | null;reasoning_config?: CustomReasoningConfig | null;+ extra_headers?: Record<string, string>;shared?: boolean;shared_by_owner?: boolean;created_at: string;@@ -225,6 +226,7 @@ export async function createProviderConfig(payload: {availableModels?: string[];maxOutputTokens?: number | null;reasoningConfig?: CustomReasoningConfig | null;+ extraHeaders?: Record<string, string>;shared?: boolean;apiKey?: string;}): Promise<ProviderConfig> {@@ -245,6 +247,9 @@ export async function createProviderConfig(payload: {...(payload.reasoningConfig === undefined? {}: { reasoning_config: payload.reasoningConfig }),+ ...(payload.extraHeaders === undefined+ ? {}+ : { extra_headers: payload.extraHeaders }),...(payload.shared === undefined ? {} : { shared: payload.shared }),encrypted_api_key: encryptedApiKey,}),@@ -278,6 +283,7 @@ export async function updateProviderConfig(availableModels?: string[];maxOutputTokens?: number | null;reasoningConfig?: CustomReasoningConfig | null;+ extraHeaders?: Record<string, string>;shared?: boolean;apiKey?: string;clearApiKey?: boolean;@@ -302,6 +308,9 @@ export async function updateProviderConfig(...(payload.reasoningConfig === undefined? {}: { reasoning_config: payload.reasoningConfig }),+ ...(payload.extraHeaders === undefined+ ? {}+ : { extra_headers: payload.extraHeaders }),...(payload.shared === undefined ? {} : { shared: payload.shared }),...(payload.apiKey === undefined ? {} : { encrypted_api_key: encryptedApiKey }),...(payload.clearApiKey === undefined ? {} : { clear_api_key: payload.clearApiKey }),@@ -354,6 +363,7 @@ export async function testProviderConnection(payload: {apiKey: string;baseUrl?: string | null;apiType?: ConnectionApiType;+ extraHeaders?: Record<string, string>;modelId?: string | null;}): Promise<ProviderTestResult> {return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {@@ -367,6 +377,9 @@ export async function testProviderConnection(payload: {encrypted_api_key: encryptedApiKey,base_url: payload.baseUrl ?? null,...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),+ ...(payload.extraHeaders === undefined+ ? {}+ : { extra_headers: payload.extraHeaders }),model_id: payload.modelId ?? null,}),});@@ -381,6 +394,7 @@ export async function listProviderModels(payload: {apiKey: string;baseUrl?: string | null;apiType?: ConnectionApiType;+ extraHeaders?: Record<string, string>;}): Promise<ProviderModelInfo[]> {return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {const response = await authFetch("/api/providers/models", {@@ -393,6 +407,9 @@ export async function listProviderModels(payload: {encrypted_api_key: encryptedApiKey,base_url: payload.baseUrl ?? null,...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),+ ...(payload.extraHeaders === undefined+ ? {}+ : { extra_headers: payload.extraHeaders }),}),});return parseJsonOrThrow<ProviderModelInfo[]>(response);diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsxindex 00d0935c717..f645948b613 100644--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx@@ -115,6 +115,7 @@ import {refreshProviderModelCatalogs,syncExternalProvidersFromBackend,} from "./sync-external-providers";+import { extraHeadersToDraft, parseExtraHeadersDraft } from "./extra-headers";const PROVIDER_FORM_EASE: [number, number, number, number] = [0.165, 0.84, 0.44, 1,@@ -299,6 +300,7 @@ export function ChatProvidersSettings({const [baseUrlDraft, setBaseUrlDraft] = useState("");const [apiType, setApiType] = useState<ConnectionApiType>("chat_completions");const [maxOutputTokensDraft, setMaxOutputTokensDraft] = useState("");+ const [extraHeadersDraft, setExtraHeadersDraft] = useState("");const [editingBackendProviderType, setEditingBackendProviderType] = useState<string | null>(null);@@ -529,6 +531,7 @@ export function ChatProvidersSettings({if (seededProviderTypeRef.current === providerType) return;seededProviderTypeRef.current = providerType;setMaxOutputTokensDraft("");+ setExtraHeadersDraft("");setApiType("chat_completions");setReasoningConfig(null);setEditingBackendProviderType(null);@@ -644,6 +647,7 @@ export function ChatProvidersSettings({setShowApiKey(false);setBaseUrlDraft("");setMaxOutputTokensDraft("");+ setExtraHeadersDraft("");setApiType("chat_completions");setReasoningConfig(null);setEditingBackendProviderType(null);@@ -819,6 +823,7 @@ export function ChatProvidersSettings({apiKey: silent ? "" : apiKey.trim(),baseUrl,apiType: providerType === LEGACY_CUSTOM_PROVIDER_TYPE ? apiType : undefined,+ extraHeaders: parseExtraHeadersDraft(extraHeadersDraft),});if (silent && autoLoadedCatalogRef.current !== autoLoad) return;// The picker keeps only ids, so per-model capabilities are learned here or lost.@@ -1001,6 +1006,7 @@ export function ChatProvidersSettings({const maxOutputTokens = supportsMaxOutputTokens? parseMaxOutputTokens(maxOutputTokensDraft): undefined;+ const extraHeaders = parseExtraHeadersDraft(extraHeadersDraft);const created = await createProviderConfig({providerType: backendProviderType,displayName,@@ -1014,6 +1020,7 @@ export function ChatProvidersSettings({reasoningConfig: isCustomReasoningConnection? (showCustomReasoning ? reasoningConfig : null): undefined,+ extraHeaders,...(showShareToggle && sharedDraft ? { shared: true } : {}),apiKey: apiKey.trim(),@@ -1039,6 +1046,7 @@ export function ChatProvidersSettings({? []: pruneProviderModelIds(providerType, availableModels),maxOutputTokens: created.max_output_tokens ?? undefined,+ extraHeaders: created.extra_headers ?? extraHeaders,reasoningConfig: created.provider_type === "custom"? normalizeCustomReasoningConfig(created.reasoning_config): undefined,@@ -1180,6 +1188,7 @@ export function ChatProvidersSettings({const maxOutputTokens = supportsMaxOutputTokens? parseMaxOutputTokens(maxOutputTokensDraft): undefined;+ const extraHeaders = parseExtraHeadersDraft(extraHeadersDraft);const updated = await updateProviderConfig(editingProviderId, {displayName: isEditingCustomProvider? customProviderName.trim() ||@@ -1193,6 +1202,7 @@ export function ChatProvidersSettings({reasoningConfig: isCustomReasoningConnection? (showCustomReasoning ? reasoningConfig : null): undefined,+ extraHeaders,...(showShareToggle && sharedDraft !== (existing.shared === true)? { shared: sharedDraft }: {}),@@ -1225,6 +1235,7 @@ export function ChatProvidersSettings({? (updated.available_models?.length ? updated.available_models : existing.availableModels): availableModelsToSave,maxOutputTokens: updated.max_output_tokens ?? undefined,+ extraHeaders: updated.extra_headers ?? extraHeaders,reasoningConfig: updated.provider_type === "custom"? normalizeCustomReasoningConfig(updated.reasoning_config): undefined,@@ -1359,6 +1370,7 @@ export function ChatProvidersSettings({getExternalMinOutputTokens(provider.providerType),).toString(),);+ setExtraHeadersDraft(extraHeadersToDraft(provider.extraHeaders));setEditingBackendProviderType(provider.backendProviderType ?? null);setModelSearchQuery("");setIsReasoningModel(@@ -1518,6 +1530,7 @@ export function ChatProvidersSettings({apiKey: savedKey,baseUrl: provider.baseUrl || null,apiType: provider.decisionsOnly ? "systemone" : provider.apiType,+ extraHeaders: provider.extraHeaders,modelId:provider.providerType === LEGACY_CUSTOM_PROVIDER_TYPE ||isDecisionConnection(provider)@@ -1870,6 +1883,36 @@ export function ChatProvidersSettings({</div>) : null}+ {providerType !== "openai_codex" ? (+ <div className="grid grid-cols-[minmax(140px,0.8fr)_minmax(0,1.2fr)] items-start gap-4 px-4 py-3 @max-[520px]:grid-cols-1">+ <div className="flex min-w-0 flex-col gap-0.5">+ <Label+ htmlFor="provider-extra-headers"+ className="text-sm font-medium"+ >+ Extra headers+ </Label>+ <p+ id="provider-extra-headers-help"+ className="text-xs leading-snug text-muted-foreground"+ >+ One header per line, as Name: value. Use {"{{CHAT_SESSION_ID}}"} for+ the open chat. Sent on every request to this connection.+ </p>+ </div>+ <Textarea+ id="provider-extra-headers"+ value={extraHeadersDraft}+ onChange={(event) => setExtraHeadersDraft(event.target.value)}+ placeholder={+ 'X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}'+ }+ aria-describedby="provider-extra-headers-help"+ className="min-h-20 font-mono text-sm"+ />+ </div>+ ) : null}+{providerType === "llama_cpp" ? (<div className="flex items-start justify-between gap-4 px-4 py-3"><div className="space-y-1">diff --git a/studio/frontend/src/features/chat/external-providers.ts b/studio/frontend/src/features/chat/external-providers.tsindex ede1749ae08..a4c11b79a5e 100644--- a/studio/frontend/src/features/chat/external-providers.ts+++ b/studio/frontend/src/features/chat/external-providers.ts@@ -26,6 +26,7 @@ export interface ExternalProviderConfig {/** The type as the backend stores it (may differ from providerType). Absent means unknown. */backendProviderType?: string;maxOutputTokens?: number;+ extraHeaders?: Record<string, string>;hasApiKey?: boolean;shared?: boolean;@@ -364,6 +365,18 @@ export function normalizeProviderMaxOutputTokens(return value;}+/** Copy saved headers into chat state. Validation lives in extra-headers.ts, loaded with Connections. */+export function extraHeadersFromSaved(+ value: unknown,+): Record<string, string> | undefined {+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;+ const headers: Record<string, string> = {};+ for (const [name, headerValue] of Object.entries(value as Record<string, unknown>)) {+ if (name && typeof headerValue === "string") headers[name] = headerValue;+ }+ return Object.keys(headers).length ? headers : undefined;+}+/** All types except ChatGPT subscriptions; both stored and UI types are checked. */export function supportsProviderMaxOutputTokens(uiProviderType: string | null | undefined,@@ -614,6 +627,7 @@ function normalizeProvider(raw: ExternalProviderConfig): ExternalProviderConfig? raw.backendProviderType.trim(): undefined,maxOutputTokens: normalizeProviderMaxOutputTokens(raw.maxOutputTokens),+ extraHeaders: extraHeadersFromSaved(raw.extraHeaders),enablePromptCaching: supportsProviderPromptCaching(providerType)? raw.enablePromptCaching !== false: undefined,diff --git a/studio/frontend/src/features/chat/extra-headers.ts b/studio/frontend/src/features/chat/extra-headers.tsnew file mode 100644index 00000000000..47ac5bd4f90--- /dev/null+++ b/studio/frontend/src/features/chat/extra-headers.ts@@ -0,0 +1,77 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++const FORBIDDEN_EXTRA_HEADERS = new Set([+ "authorization",+ "proxy-authorization",+ "cookie",+ "set-cookie",+ "host",+ "content-length",+ "content-type",+ "connection",+ "transfer-encoding",+ "te",+ "trailer",+ "upgrade",+ "keep-alive",+ "api-key",+ "x-api-key",+ "x-goog-api-key",+]);+const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;+const HEADER_VALUE_RE = /^[\t\x20-\x7e]*$/;+const MAX_EXTRA_HEADERS = 16;++export function extraHeadersToDraft(+ headers: Record<string, string> | undefined,+): string {+ return Object.entries(headers ?? {})+ .map(([name, value]) => `${name}: ${value}`)+ .join("\n");+}++export function parseExtraHeadersDraft(draft: string): Record<string, string> {+ const trimmed = draft.trim();+ if (!trimmed) return {};+ const entries: [string, unknown][] = [];+ if (trimmed.startsWith("{")) {+ const parsed: unknown = JSON.parse(trimmed);+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {+ throw new Error("Extra headers JSON must be an object of header names to string values.");+ }+ entries.push(...Object.entries(parsed as Record<string, unknown>));+ } else {+ for (const line of trimmed.split("\n")) {+ const text = line.trim();+ if (!text || text.startsWith("#")) continue;+ const separator = text.indexOf(":");+ if (separator <= 0) {+ throw new Error(`Invalid extra header line: ${text}`);+ }+ entries.push([text.slice(0, separator), text.slice(separator + 1)]);+ }+ }+ const headers: Record<string, string> = {};+ for (const [rawName, rawValue] of entries) {+ const name = rawName.trim();+ if (typeof rawValue !== "string") {+ throw new Error(`Header ${name} must have a string value.`);+ }+ const value = rawValue.trim();+ if (!HEADER_NAME_RE.test(name)) {+ throw new Error(`Invalid extra header name: ${name}`);+ }+ if (FORBIDDEN_EXTRA_HEADERS.has(name.toLowerCase())) {+ throw new Error(`Cannot set reserved header ${name}.`);+ }+ if (!HEADER_VALUE_RE.test(value)) {+ throw new Error(`Header ${name} must be printable ASCII.`);+ }+ headers[name] = value;+ }+ if (Object.keys(headers).length > MAX_EXTRA_HEADERS) {+ throw new Error(`At most ${MAX_EXTRA_HEADERS} extra headers are allowed.`);+ }+ return headers;+}diff --git a/studio/frontend/src/features/chat/sync-external-providers.ts b/studio/frontend/src/features/chat/sync-external-providers.tsindex c2f300e52ee..b7cebb50d71 100644--- a/studio/frontend/src/features/chat/sync-external-providers.ts+++ b/studio/frontend/src/features/chat/sync-external-providers.ts@@ -28,6 +28,7 @@ import {CUSTOM_PROVIDER_PRESETS,connectionApiFields,type ExternalProviderConfig,+ extraHeadersFromSaved,getExternalProviderApiKey,isPromptCacheTtl,LEGACY_CUSTOM_PROVIDER_TYPE,@@ -302,6 +303,7 @@ export async function syncExternalProvidersFromBackend(models: resolvedModels,availableModels: resolvedAvailableModels,maxOutputTokens: config.max_output_tokens ?? undefined,+ extraHeaders: extraHeadersFromSaved(config.extra_headers),reasoningConfig:config.provider_type === "custom" &&config.api_type !== "responses" && config.api_type !== "systemone"diff --git a/studio/frontend/src/features/chat/utils/chat-title.ts b/studio/frontend/src/features/chat/utils/chat-title.tsindex 718eff8bc7f..ef451964cf5 100644--- a/studio/frontend/src/features/chat/utils/chat-title.ts+++ b/studio/frontend/src/features/chat/utils/chat-title.ts@@ -200,6 +200,7 @@ export interface ExternalRoutingFields {provider_api_type: "chat_completions" | "responses";provider_reasoning_config?: CustomReasoningConfig;encrypted_api_key?: string;+ extra_headers?: Record<string, string>;}export type ExternalRoutingUnavailableReason =@@ -275,6 +276,9 @@ export async function buildExternalRoutingFields(apiKey,options.forceRefreshPublicKey ?? false,),+ ...(provider.extraHeaders && Object.keys(provider.extraHeaders).length+ ? { extra_headers: provider.extraHeaders }+ : {}),}: {}),};diff --git a/studio/frontend/tests/custom-provider-api-type.test.ts b/studio/frontend/tests/custom-provider-api-type.test.tsindex cf0cec3d01f..3d015273598 100644--- a/studio/frontend/tests/custom-provider-api-type.test.ts+++ b/studio/frontend/tests/custom-provider-api-type.test.ts@@ -34,3 +34,66 @@ test("Responses survives provider requests and cache while legacy cache defaultsproviders.saveExternalProviders([config]);assert.equal(providers.loadExternalProviders()[0].apiType, "chat_completions");});++test("extra header drafts round-trip and reject reserved names", async () => {+ const headers = await vite.ssrLoadModule("/src/features/chat/extra-headers.ts");+ const parsed = headers.parseExtraHeadersDraft(+ "X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}\nX-Title: Unsloth\n",+ );+ assert.equal(parsed["X-LiteLLM-Session-Id"], "unsloth-{{CHAT_SESSION_ID}}");+ assert.equal(+ headers.extraHeadersToDraft(parsed),+ "X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}\nX-Title: Unsloth",+ );+ assert.throws(() => headers.parseExtraHeadersDraft("Authorization: Bearer secret"));+ const json = headers.parseExtraHeadersDraft('{"X-Title":"Studio"}');+ assert.equal(json["X-Title"], "Studio");+ assert.throws(() => headers.parseExtraHeadersDraft('{"Authorization":"nope","X-Title":"ok"}'));+ assert.throws(() => headers.parseExtraHeadersDraft('{"X-Count":1}'));+ const many = Object.fromEntries(Array.from({ length: 17 }, (_, i) => [`X-H${i}`, "v"]));+ assert.throws(() => headers.parseExtraHeadersDraft(JSON.stringify(many)), /At most 16/);+});++test("explicit-key routing sends extra headers; a saved key leaves them on the record", async () => {+ const routing = await vite.ssrLoadModule("/src/features/chat/utils/chat-title.ts");+ const extraHeaders = { "X-Title": "Unsloth" };+ const provider = {+ id: "gateway",+ providerType: "custom",+ name: "Gateway",+ baseUrl: "https://gateway.example/v1",+ models: ["proxy-model"],+ extraHeaders,+ createdAt: 1,+ updatedAt: 1,+ };+ const saved = await routing.buildExternalRoutingFields({+ provider,+ modelId: "proxy-model",+ apiKey: "",+ });+ assert.equal("extra_headers" in saved, false);+ assert.equal("encrypted_api_key" in saved, false);++ const previous = globalThis.fetch;+ globalThis.fetch = (async () =>+ Response.json({+ public_key: `-----BEGIN PUBLIC KEY-----+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1n8QOqkDXkFEOC62kiqZcBCN3+l/DmD+0BGvjg8h1fFJD2Fla1ibcnmKb9Vok+PmR6jm1JX0yu8JHXPw1om01RwQWe+nehl2VzGfdEdNaRoKhW5oVsnnfmxlWJ/qWuV2rDK8DK/6UK9sC/duMkRWaRGdhyl+l+8/fuJc9JDRVzx7HwIDAQAB+-----END PUBLIC KEY-----`,+ })) as typeof fetch;+ try {+ const explicit = await routing.buildExternalRoutingFields({+ provider,+ modelId: "proxy-model",+ apiKey: "sk-browser-held",+ });+ assert.deepEqual(explicit.extra_headers, extraHeaders);+ assert.equal(typeof explicit.encrypted_api_key, "string");+ } finally {+ globalThis.fetch = previous;+ }+});