Models & Providers

🔌 Models & Providers

Bring your own key — any provider, any gateway. Model changes take effect on the next request; no restart needed.

The 60-second setup

1. Settings → Models
2. Add provider (catalog: OpenAI, Anthropic, DeepSeek, Google, Mistral, Groq, …) or Add a custom provider
3. Paste the base URL — provider ID + display name auto-fill
4. Enter your API key
5. Fetch available models → click to add, or enter by hand
6. Pick a model in the composer — you're live

Where keys live

• Keys are stored in $DSH_HOME/.credentials.yaml with owner-only permissions.
• Settings files hold only a credential reference — never the literal secret.
• The Models page receives a redacted descriptor after save; the page can't echo a key back. Write-only by design.

Catalog vs custom providers

	Catalog provider	Custom provider
Endpoint	Installed automatically	You paste it
Protocol	Declared by the catalog	You pick (openai-completions, openai-responses, …)
Models	From the catalog (capacities included)	Auto-discovered via GET /models, or hand-entry
Probe	No network needed	Queries the endpoint you typed

Supported listing protocols for auto-discovery: OpenAI Chat Completions and OpenAI Responses. Anthropic-style gateways and OAuth-only endpoints (Azure, Codex) fall back to hand-entry — by design, not a bug.

Vision models on custom endpoints

A hand-entered model is treated as text-only until it declares otherwise — attaching an image is refused before send. Make it serve images with one line in $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: vision-preview
          input: [text, image]

Route-wide fallback instead of per-model edits:

  defaultInput: [text, image]

Context window & output caps

Model rows carry context badges in the UI. A hand-entered model gets conservative fallbacks; set exact values on the model row (contextWindow, maxTokens) or accept K/M shorthand (1M, 256K) in the editor. Overflow is detected against the declared window and surfaces as a coded failure, not a silent truncation.

Native-auth providers

Bedrock (AWS creds + region), Vertex (ADC project), Azure (api-version), and Codex (OAuth) authenticate natively — filling only the API-key field does not configure them. The provider card names what it needs.

Connection testing

Every provider card has a Test connection action: it probes the endpoint live and answers with the reachable model list or the exact failure (401 → "check the API key"). Enabled/disabled toggles and per-model badges keep the page readable at a glance.

---

Provider ID warning: it's permanent — requests, sessions, defaults, and credential references bind to it. To rename, add the new provider and retire the old one; the display name and endpoint stay editable.