Skip to content
Documentation
Valdr UI
Settings

Settings

Settings is where you wire up the infrastructure behind every agent launch. Define which AI providers are available, create reusable presets that encode exactly how agents should run, and import or export packs to standardize your setup. Configure once, launch confidently every time.

What this page covers

  • Agent Presets — Create, edit, export, and import launcher configurations
  • Providers — Register AI providers and manage model availability
  • Valdr Packs — Import and export packs for portable agent configurations

Agent Presets

Agent presets are saved launcher configurations. Each preset bundles a provider, model, worktree policy, environment references, and runtime config into a reusable one-click launch target. Instead of re-configuring every agent session from scratch, you pick a preset and go.

All your launcher presets in one place — pick a provider, set it up once, reuse everywhere

Preset table columns

ColumnWhat it shows
KeyUnique identifier for the preset (e.g., coder-claude, orchestrator-ollama). Used when launching agents from the UI or via MCP.
ProviderThe AI provider this preset targets, shown with its icon (e.g., Claude, Codex, Ollama).
Env refsEnvironment variable names the preset needs at runtime (e.g., CODEX_API_KEY). A dash means no env refs required.

Creating a preset

Click the + button in the toolbar to open the preset form. Every field shapes how agents behave when launched with this preset:

Full control over every launch parameter — provider, model, permissions, worktree isolation, and runtime config
FieldPurpose
KeyA unique slug that identifies this preset. Set once at creation, immutable afterward. Choose something descriptive: coder-claude, reviewer-codex, orchestrator-ollama.
Display nameHuman-readable label shown in launcher dropdowns (e.g., “Claude Coder”).
ProviderWhich registered provider to use. The dropdown shows all providers from the Providers tab.
ModelWhich model to use from the selected provider’s model list (e.g., Opus, Sonnet, gpt-5.4).
DescriptionOptional note about what this preset is for. Helps when you have many presets.
Env refsComma-separated environment variable names the agent session needs (e.g., CODEX_API_KEY, OPENAI_API_KEY). Valdr passes these references through to the agent runtime. Treat raw session metadata and spec exports as sensitive if they include provider settings.
Config JSONRaw JSON configuration passed to the agent launcher. Controls permission modes, allowed tools, keep-alive timeouts, and other runtime behavior.

Worktree options

The three checkboxes at the bottom of the preset form control git worktree behavior:

OptionWhat it does
Create worktree by defaultWhen checked, every agent session launched with this preset gets its own isolated git worktree. Changes stay off your active branch until you review and merge.
Allow reuse existing worktreeWhen checked, agents can reuse a worktree from a previous session instead of creating a fresh one. Useful for multi-step workflows on the same branch.
Allow ad-hoc overridesWhen checked, users can override worktree settings per-launch. When unchecked, the preset’s defaults are enforced.
Keep worktree creation on by default. Isolated worktrees reduce branch-level blast radius and make review easier before you merge changes back. They are a workflow boundary, not an OS sandbox.

Export and import

Use the Export and Import buttons to move presets between machines or share them with teammates.

  • Export saves all presets (or a selection) as a portable file
  • Import loads presets from a file, with conflict detection if a key already exists

This makes onboarding fast — set up presets once, export, and every team member imports the same configuration. Combined with Valdr Packs and provider/preset configuration, you can standardize an entire team’s agent infrastructure in minutes.

Providers

The Providers tab is where you register the AI providers Valdr can use. Each provider entry defines a connection type, available models, and a default model. Agent presets reference these providers, so providers must be registered before you can create presets that use them.

Three providers configured — cloud and local models side by side, each with its own model roster

Provider table columns

ColumnWhat it shows
ProviderDisplay name and icon (e.g., Claude Code, Codex, Ollama Local).
TypeThe provider integration type (e.g., claude, codex, ollama). Determines how Valdr communicates with the provider.
EnabledWhether this provider is available for use in presets and launches. Disable a provider to temporarily remove it without deleting the configuration.
Default ModelThe model used when no specific model is selected (e.g., sonnet, gpt-5.4, qwen3-coder-next).
ModelsHow many models are registered under this provider. Click Edit to see and manage the full model list.

Adding a provider

Click + to register a new provider. You need:

  1. A display name — what you see in dropdowns and tables
  2. A type — the integration protocol (claude, codex, ollama, etc.)
  3. At least one model — the models available through this provider
  4. A default model — which model to use when none is specified

Mixing cloud and local providers

Valdr treats all providers equally. Run Claude for complex coding tasks and Ollama for fast local iteration — switch between them by choosing a different preset. This gives you:

  • Cost control — use cheaper or free local models for exploratory work
  • Offline capability — Ollama presets work without internet
  • Comparison — run the same task with different providers and compare session quality in the Agent Sessions view

Export and import

Like presets, providers support Export and Import for portable configuration. Export your provider setup and share the JSON so teammates import identical provider configurations. See Provider Configuration for the full JSON format.

Valdr Packs

The Valdr Packs tab handles import and export of .valdr-pack.tar.gz archives — portable bundles that package agents, prompts, capabilities, and configuration into a single shareable file.

Export your entire agent setup as a portable archive — import it on another machine and be productive immediately

Exporting a pack

  1. Select pack keys — choose which packs to include in the export (e.g., valdr)
  2. Filter by agent handles (optional) — limit the export to specific agents (e.g., @executor, @reviewer)
  3. Click Export Pack to generate the .valdr-pack.tar.gz archive

The exported archive includes all agents, prompts, capabilities, and configuration associated with the selected packs.

Importing a pack

Click Import Pack to load an archive. Valdr runs a conflict-aware preflight check before committing any changes:

  • Detects naming conflicts with existing agents, prompts, or capabilities
  • Shows what will be added, updated, or skipped
  • Requires explicit confirmation before applying changes

This means you can safely import packs without worrying about overwriting your existing setup.

Valdr Packs are the fastest way to standardize agent configurations across machines. Export once, import everywhere — every machine gets the same agents, prompts, and capabilities. Learn more about pack authoring in the Valdr Packs guide.

How settings flow into agent launches

Settings aren’t just configuration — they’re the foundation of every agent session. Here’s how the pieces connect:

  1. Register providers in the Providers tab (e.g., Claude, Codex, Ollama)
  2. Create presets in Agent Presets that reference those providers with specific models and runtime config
  3. Launch agents from Tasks or the Orchestrator using your presets
  4. Review results in Agent Sessions — every session records which preset and provider was used

Change a preset once and every future launch inherits the update. No re-configuring, no drift, no “which model was that session using?” questions.

Next steps

Ready to put your settings to work? Launch your first agent from a task and see how presets turn configuration into one-click execution.

PromptsSystem Monitoring