Provider Configuration

A provider setup registers an AI model backend with Valdr. It defines what a provider is — display name, integration type, available models, API key requirements, and enablement status. Provider setups are managed in Settings > Providers and can be exported/imported as JSON.

JSON schema

Each provider setup is a JSON object with this shape:

{
  "providerId": "codex",
  "providerType": "codex",
  "displayName": "Codex",
  "isEnabled": true,
  "apiKeyEnvVar": "CODEX_API_KEY",
  "baseUrl": null,
  "defaultModel": "gpt-5.4",
  "defaultTemperature": null,
  "defaultMaxTokens": null,
  "models": [
    { "id": "gpt-5.4", "label": "GPT-5.4" },
    { "id": "gpt-5.4-mini", "label": "GPT-5.4 Mini" }
  ]
}

Field reference

Registered provider types

These are the valid providerType values:

Native providers (claude, codex) use the vendor’s SDK directly with full agentic capabilities including session resumption. ollama routes through the TanStack adapter layer where Valdr manages tool execution server-side.

What provider setups affect at runtime

Not all provider setup fields become runtime launcher defaults. This distinction matters:

Runtime defaults for native launchers come from environment variables (see per-provider config below). Launch-time behavior comes from the resolved preset config.

Per-provider config keys

Each provider accepts different config keys in presets. These are the operator-facing fields your presets can set:

Claude

Current launcher fallback: If permissionMode is omitted, Claude currently falls back to bypassPermissions. For clearer human review and audit posture, set the mode explicitly and prefer stricter modes unless you intentionally want unattended local execution. allowedTools defaults to ["Read", "Edit", "Write", "Glob", "Grep", "Bash"].

Environment variables: CLAUDE_MODEL, CLAUDE_PERMISSION_MODE, CLAUDE_MAX_TURNS, CLAUDE_ALLOWED_TOOLS, CLAUDE_DISALLOWED_TOOLS.

Codex

Authentication: Dual strategy — cached login (~/.codex/auth.json) first, API key fallback via CODEX_API_KEY (falls back to OPENAI_API_KEY).

Environment variables: CODEX_API_KEY, CODEX_BASE_URL, CODEX_MODEL, CODEX_TEMPERATURE, CODEX_MAX_OUTPUT_TOKENS.

Ollama

Ollama uses the TanStack adapter layer with Valdr-managed tool execution, so permissionMode, allowedTools, and mcpServers are not supported.

Examples

Claude Code

{
  "providerId": "claude",
  "providerType": "claude",
  "displayName": "Claude Code",
  "isEnabled": true,
  "apiKeyEnvVar": null,
  "baseUrl": null,
  "defaultModel": "sonnet",
  "defaultTemperature": null,
  "defaultMaxTokens": null,
  "models": [
    { "id": "default", "label": "Default" },
    { "id": "sonnet", "label": "Sonnet" },
    { "id": "sonnet[1m]", "label": "Sonnet 1M" },
    { "id": "opus", "label": "Opus" },
    { "id": "haiku", "label": "Haiku" },
    { "id": "opusplan", "label": "Opus Plan" }
  ]
}

Codex

{
  "providerId": "codex",
  "providerType": "codex",
  "displayName": "Codex",
  "isEnabled": true,
  "apiKeyEnvVar": "CODEX_API_KEY",
  "baseUrl": null,
  "defaultModel": "gpt-5.4",
  "defaultTemperature": null,
  "defaultMaxTokens": null,
  "models": [
    { "id": "gpt-5.4", "label": "GPT-5.4" },
    { "id": "gpt-5.4-mini", "label": "GPT-5.4 Mini" },
    { "id": "gpt-5.3-codex", "label": "GPT-5.3 Codex" },
    { "id": "gpt-5.3-codex-spark", "label": "GPT-5.3 Codex Spark" }
  ]
}

Ollama (local)

{
  "providerId": "ollama",
  "providerType": "ollama",
  "displayName": "Ollama Local",
  "isEnabled": true,
  "apiKeyEnvVar": null,
  "baseUrl": "http://localhost:11434",
  "defaultModel": "qwen3-coder-next",
  "defaultTemperature": null,
  "defaultMaxTokens": null,
  "models": [
    { "id": "qwen3-coder-next", "label": "Qwen3-Coder-Next" },
    { "id": "qwen3", "label": "Qwen3" },
    { "id": "deepseek-r1", "label": "DeepSeek R1" }
  ]
}

Import and export

Use Export and Import in Settings > Providers. The export produces a JSON array of provider setup objects. Import on another machine to replicate the provider catalog instantly.

Next steps

Providers define what Valdr can talk to. Presets define how — the specific model, permissions, and runtime config for each agent launch.