Provider Configuration

A provider setup registers an integration with Valdr. Give it a display name, choose its type, and enable it. Model lists and connection defaults are optional. Manage provider setups in Settings > Providers, or export/import them 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:

Claude, Codex, and OpenCode support continuing an existing session.

Provider settings and session settings

Provider setups organize the names and model choices shown in Settings. To select the model, endpoint, temperature, or token limits for a session, set those values in the preset’s config; catalog defaults alone do not set them for every session.

If the provider needs an API key, apiKeyEnvVar identifies the environment variable to use unless the preset supplies its own credential reference. OpenCode uses its saved authentication or explicit credential references instead.

Per-provider config keys

Use shared Valdr keys for model selection, environment overrides, and supported MCP connections. Put additional provider-specific settings in a flat config.native object. Shared settings take precedence over corresponding native settings. See the preset reference for config.env and config.native, including version requirements.

Claude

Claude does not use keepAliveMs. Use maxTurns to bound the number of agent turns per prompt.

When neither the preset nor environment sets these options, permissionMode is default and allowedTools adds no approvals. Valdr access is configured automatically.

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

Codex

Authentication: Sign in with codex login, or set CODEX_API_KEY (OPENAI_API_KEY also works as a fallback).

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

OpenCode

1. Add an enabled provider with type OpenCode in Settings > Providers.
2. Leave API key env var, Base URL, Default model, and Default max tokens empty. Models can stay []; other defaults can stay as they are.
3. Create presets in Settings > Agent Presets and select the model in Config JSON, for example:

{
  "model": "openai/gpt-6-sol",
  "agent": "build"
}

Use a model available to your OpenCode account. OpenCode handles its own sign-in and settings. A preset can also use config: {} to keep OpenCode’s defaults, with env: [] when no environment references are needed.

MCP servers are optional. Omit mcpServers unless you want to add or override an MCP connection for that preset. See the complete preset example.

OpenCode requires a stable 1.18.x executable on the machine running Valdr, on PATH or selected with the preset’s executable setting.

OpenCode supports executor, reviewer, and auditor sessions. Queued follow-ups continue the same conversation; active-turn steering is unavailable. Start a new session after changing a preset so it uses the new configuration.

Ollama

Ollama does not support permissionMode, allowedTools, or additional mcpServers.

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" }
  ]
}

OpenCode — empty provider setup

{
  "providerId": "opencode",
  "providerType": "opencode",
  "displayName": "OpenCode",
  "isEnabled": true,
  "apiKeyEnvVar": null,
  "baseUrl": null,
  "defaultModel": null,
  "models": []
}

Choose models in presets; no model list or connection defaults are needed here.

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.