Customization Guide

Providers and presets are designed to be customized. This page covers what you should tune, what to leave alone, and how to build configurations for different agent roles and providers.

Model and sampling parameters

Swap models freely

Change the model field in your preset. If you use a provider model list for UI selection, you can update that list too. OpenCode does not need a model list in Valdr; use its provider/model identifier directly in the preset.

"config": {
  "model": "opus"
}

Tune temperature and tokens per role

These are starting points for providers that accept sampling and output-token settings, such as Codex and Ollama. Claude uses its own supported settings, including maxTurns; OpenCode uses native provider/model configuration. Check the per-provider keys before copying a setting.

Keep-alive timeouts

keepAliveMs controls Codex session idle time and how long Ollama keeps a model loaded. Claude does not use this setting. OpenCode uses startupTimeoutMs and timeoutMs for startup and turn limits.

Worktree policy by role

Permission and tool access (Claude)

Claude presets control what tools the agent can use:

"config": {
  "permissionMode": "acceptEdits",
  "allowedTools": []
}

• permissionMode: "default" uses standard permission checks for tools that are not already approved
• permissionMode: "acceptEdits" automatically approves file edits and supported filesystem operations; other tools still follow permission rules
• permissionMode: "plan" is for exploration and planning; file edits are not automatically approved
• permissionMode: "bypassPermissions" is a high-trust option for unattended local execution
• allowedTools lists tools to approve without prompting. An empty array adds no tool approvals; unlisted tools remain subject to the permission mode and rules
• disallowedTools blocks specific tools

Valdr access is configured automatically. See Claude permission modes and rules when choosing approvals for additional tools.

Reasoning effort (Codex and Claude)

Codex and Claude support reasoning effort configuration:

"config": {
  "model_preferences": {
    "reasoning_effort": "medium"
  }
}

Claude accepts low, medium, high, xhigh, and max. Codex also accepts ultra and the legacy value minimal. Availability depends on the selected model and runtime; invalid values produce a launch error.

At launch, Use preset/default inherits the preset or runtime setting. Omit the effort key to use the runtime default. OpenCode uses its native variant selector instead; Ollama has no generic reasoning-effort setting.

Native settings and launch environment

Save launch environment values in config.env and additional provider settings in config.native. Both belong in the preset’s Config JSON field, so you can reuse and export the configuration. Native passthrough, OpenCode environment overrides, and Ollama OLLAMA_HOST overrides require Valdr 0.3.7 or later. Codex and Claude environment overrides also work in earlier releases.

{
  "model": "gpt-5.4",
  "env": { "TZ": "UTC" },
  "native": { "web_search": "disabled" }
}

This is a Codex configuration. The env values must be strings; native accepts the selected launcher’s JSON settings without a provider-name wrapper. Shared Valdr fields take precedence. When switching providers, use that provider’s native settings surface.

Read-only code review with OpenCode

Use a read-only code reviewer to check supplied source files for bugs and report findings without making edits. Define an OpenCode agent in native.agent, then select it with the shared agent field. Set inheritance flags and dedicated configuration paths through env to choose which OpenCode configuration the session loads.

Paste this object into Config JSON for an OpenCode preset. Replace the model and absolute paths, create the dedicated directories, and make REVIEW_API_KEY available to the process running Valdr. Dedicated HOME/XDG paths redirect the default authentication file locations, so this example uses an explicit credential reference.

{
  "model": "openai/gpt-6-sol",
  "agent": "reviewer",
  "apiKey": "$env:REVIEW_API_KEY",
  "env": {
    "HOME": "/absolute/path/opencode-reviewer",
    "XDG_CONFIG_HOME": "/absolute/path/opencode-reviewer/config",
    "XDG_DATA_HOME": "/absolute/path/opencode-reviewer/data",
    "XDG_CACHE_HOME": "/absolute/path/opencode-reviewer/cache",
    "XDG_STATE_HOME": "/absolute/path/opencode-reviewer/state",
    "OPENCODE_DISABLE_PROJECT_CONFIG": "1",
    "OPENCODE_DISABLE_EXTERNAL_SKILLS": "1",
    "OPENCODE_DISABLE_CLAUDE_CODE": "1"
  },
  "native": {
    "share": "disabled",
    "agent": {
      "reviewer": {
        "mode": "primary",
        "prompt": "Review the supplied source files for bugs and explain your findings. Do not edit files.",
        "permission": {
          "*": "deny",
          "read": "allow",
          "external_directory": "deny",
          "skill": "deny"
        }
      }
    },
    "experimental": { "continue_loop_on_deny": true }
  }
}

The disable flags reduce project and external skill context; dedicated HOME/XDG paths redirect the default user configuration locations. Adding native settings alone does not remove inherited agents, plugins, skills, or instructions. Dedicated paths do not disable inherited OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_CONFIG_CONTENT, or OPENCODE_AUTH_CONTENT. Remove any inherited overrides you do not want this preset to load before starting Valdr. Keep the dedicated directories limited to the intended configuration, and start a new session after changing the preset.

These controls do not provide complete filesystem or instruction isolation. OpenCode can still load nested AGENTS.md during reads, and file permissions may allow symlink targets outside an approved directory. Do not rely on this preset alone for strict filesystem isolation.

Ollama environment and native options

Ollama’s config.env.OLLAMA_HOST selects an existing API endpoint when baseUrl is absent. It does not launch or reconfigure the Ollama server, and other environment entries do not affect Valdr tools. Put model options such as num_ctx and seed under native.options. Shared temperature, maxOutputTokens, and a positive keepAliveMs take precedence over their corresponding native options. See the Ollama preset example.

MCP server attachment

Claude, Codex, and OpenCode presets can attach additional MCP servers. This is optional. Leave mcpServers out when you do not need to add or override a connection.

For example:

"config": {
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server.js"]
    }
  }
}

Provider differences:

• Claude: Valdr access is always available. Use mcpServers to add other servers; it cannot replace the Valdr connection.
• Codex: Valdr access is enabled by default. Use mcpServers to add other servers.
• OpenCode: mcpServers can be omitted. Ad-hoc sessions reuse MCP connections configured in OpenCode. A preset entry replaces a connection with the same name. Workflow runs receive Valdr access automatically; if you override that connection, use a direct Valdr stdio command under mcpServers.valdr. Remote Valdr connections and other Valdr connection names are not supported for workflow runs.
• Ollama: Additional MCP servers are not supported.

Use an absolute script path so the server still starts when the session runs in a different worktree. Credential handling is provider-specific; a string such as "from-env" is a literal value, not an environment reference. Configure credentials through the server’s supported environment mechanism and keep secret values out of exported presets.

What not to change

Never hard-code secrets

Always use env refs:

// ✅ Correct
"env": [{ "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }]

// ❌ Wrong — never do this
"config": { "apiKey": "sk-abc123..." }

Import validation rejects packs with inline secrets.

Keep role semantics consistent

Name presets by role: coder-claude, reviewer-codex, orchestrator-ollama. Clear names make the right configuration easier to select. Use settings appropriate for each role.

Don’t widen tool access without understanding the implications

Expanding allowedTools or changing permissionMode can grant the agent more access. Review those permissions before starting unattended work.

Building role-specific presets

Coders

Coding presets usually benefit from worktree isolation and an explicit permission mode:

{
  "key": "coder-claude",
  "providerType": "claude",
  "config": {
    "model": "opus",
    "permissionMode": "acceptEdits",
    "allowedTools": []
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Reviewers

Focused evaluation with consistent output:

{
  "key": "reviewer-claude",
  "providerType": "claude",
  "config": {
    "model": "sonnet",
    "permissionMode": "default",
    "allowedTools": []
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Orchestrators

Coordination presets — no worktree needed and usually no reason to skip confirmations:

{
  "key": "orchestrator-claude",
  "providerType": "claude",
  "config": {
    "model": "sonnet",
    "permissionMode": "plan",
    "allowedTools": []
  },
  "worktree": { "shouldCreateWorktree": false, "allowReuseExistingWorktree": true }
}

Local development (Ollama)

Free, offline, and fast for iteration:

{
  "key": "coder-ollama",
  "providerType": "ollama",
  "config": {
    "model": "qwen3-coder-next",
    "baseUrl": "http://localhost:11434",
    "temperature": 0.1,
    "maxOutputTokens": 4096,
    "keepAliveMs": 300000
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Sharing configurations

1. Configure providers and presets in the UI
2. Export both from Settings (produces provider-defaults.json and agent-launcher-presets.json)
3. Share the JSON files — teammates Import them for identical configurations

When you update a preset, re-export it and have each person import the reviewed file into their local workspace. Sharing files does not synchronize running instances or change existing sessions.

Next steps

Configure your providers and presets in Settings, then put them to work by launching your first agent.