Preset Configuration

A provider preset saves the settings for an agent session: provider, model, permissions, environment references, and worktree options. Manage presets in Settings > Agent Presets, or export/import them as JSON.

Full record shape

This is the complete preset shape as stored, exported, and imported:

{
  "key": "coder-codex",
  "displayName": "Codex Coder",
  "providerType": "codex",
  "description": "Codex preset for coding tasks.",
  "tags": ["coding"],
  "allowAdhocOverrides": true,
  "config": {
    "model": "gpt-5.4",
    "keepAliveMs": 120000,
    "model_preferences": {
      "reasoning_effort": "medium"
    },
    "env": { "TZ": "UTC" },
    "native": { "web_search": "disabled" }
  },
  "env": [
    { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
  ],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": false
  }
}

Field reference

Top-level fields

config object

Use shared Valdr keys for settings such as model, env, and mcpServers, and native for settings specific to the selected launcher. See Provider Configuration for supported keys.

In Config JSON, paste the contents of this object. When importing a full preset record, keep it inside "config".

Timeout settings vary by provider. See Keep-alive timeouts for supported settings and examples.

config.env object

Set environment values for an individual session with a string-valued object:

{
  "config": {
    "env": { "TZ": "UTC" }
  },
  "env": []
}

Values must be strings: use "1", rather than true or 1, for a native environment flag. Values are literal; $env:NAME is not expanded inside this object. Keep credentials in supported environment reference fields, rather than embedding them in config.env.

config.native object

Pass additional settings to the selected launcher as a flat JSON object:

{
  "config": {
    "model": "gpt-5.4",
    "native": { "web_search": "disabled" }
  }
}

Use "native": { ... } directly, without a provider-name wrapper. Shared Valdr settings take precedence over corresponding native settings. Native settings are provider-specific; review them when changing a preset’s provider.

Native passthrough does not automatically exclude the launcher’s existing configuration. For OpenCode inheritance controls, see read-only code review example.

Use config.mcpServers to add MCP connections. For Codex, native mcp_servers is unsupported. OpenCode provider credentials and headers inside native must use environment references.

env array

This array maps names used by environment references to environment variables available to the process running Valdr. It is separate from config.env: adding a reference here does not set an environment variable in the launched agent. Referenced values are read at launch time and are not embedded in the preset.

"env": [
  { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
]

Set "env": [] when no reference aliases are needed, including when using the provider’s saved sign-in.

worktree object

Choose whether sessions create a new git worktree or reuse an existing one.

Using preset settings

Presets supply the saved settings for each new session. You can reference credentials from your environment and adjust settings for an individual run.

{ "apiKey": "$env:CODEX_API_KEY" }
{ "baseUrl": { "envRef": "OPENAI_BASE_URL" } }

Examples

Claude — coding preset

{
  "key": "coder-claude",
  "displayName": "Claude Coder",
  "providerType": "claude",
  "description": "Claude Code Coder",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "opus",
    "allowedTools": [],
    "env": { "TZ": "UTC" },
    "native": { "settingSources": ["project"] }
  },
  "env": [],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": true
  }
}

Codex — coding preset

{
  "key": "coder-codex",
  "displayName": "Codex",
  "providerType": "codex",
  "description": "OpenAI Codex preset.",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "gpt-5.4",
    "keepAliveMs": 120000,
    "model_preferences": {
      "reasoning_effort": "medium"
    },
    "env": { "TZ": "UTC" },
    "native": { "web_search": "disabled" }
  },
  "env": [
    { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
  ],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": false
  }
}

OpenCode — coding preset

{
  "key": "coder-opencode",
  "displayName": "OpenCode Coder",
  "providerType": "opencode",
  "tags": ["coding"],
  "config": {
    "model": "openai/gpt-6-sol",
    "agent": "build",
    "env": { "TZ": "UTC" },
    "native": { "share": "disabled" }
  },
  "env": [],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": true
  }
}

The OpenCode provider can have an empty model list. Set config.model to a model available through OpenCode, and optionally choose an agent such as build. OpenCode handles its own sign-in; the top-level env reference array can remain empty while config.env supplies non-secret launch settings.

config.agent selects an agent by name. config.native.agent defines agents as a map. See the read-only code review example to define an agent, restrict its tools, and reduce inherited context.

mcpServers is optional and is omitted from this example. Add it only when the preset needs an MCP connection or override. You can also use config: {} to keep OpenCode’s defaults. See OpenCode configuration.

Ollama — local orchestration preset

{
  "key": "orchestrator-ollama",
  "displayName": "Ollama Local",
  "providerType": "ollama",
  "description": "Local Ollama preset.",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "qwen3-coder-next",
    "env": { "OLLAMA_HOST": "http://localhost:11434" },
    "native": { "options": { "num_ctx": 8192 } },
    "temperature": 0.1,
    "maxOutputTokens": 4096,
    "keepAliveMs": 300000
  },
  "env": [],
  "worktree": {
    "shouldCreateWorktree": false,
    "allowReuseExistingWorktree": true
  }
}

An explicit config.baseUrl takes precedence over the Ollama example’s config.env.OLLAMA_HOST.

Import and export

Use Export and Import in Settings > Agent Presets. The export produces a JSON array of preset records.

Preset export/import can also be bundled with provider setups in a provider pack format:

{
  "version": "1.0",
  "exportedAt": 1712700000000,
  "providerDefaults": [ /* provider setup records */ ],
  "presets": [ /* preset records */ ]
}

Import validation rejects packs with inline secrets.

Next steps

See the Customization Guide for guidance on building role-specific presets and what to lock down for production.