Configure Valdr

Valdr is installed and running. Now wire it up. This page walks through the three steps that turn a fresh install into a working agent operations platform: install packs, register providers, and configure your first project. Most of this takes under five minutes.

What this page covers

• Installing Valdr packs (agents, prompts, capabilities, and workflows)
• Registering AI providers and creating agent presets
• Setting up your first project

1. Install Valdr Packs

Valdr packs bundle agents, prompts, capabilities, and workflow definitions into portable archives. The core pack supplies the general orchestrators and agent roles. Sovereign users can also import the separately released Valdr Workflow pack for Verdandi and the included durable workflows.

Compatible releases

Use the latest Valdr CLI release and the latest release of each pack from the Valdr Packs releases page:

1. Download the core archive for your tier: valdr-raider.valdr-pack.tar.gz, valdr-vanguard.valdr-pack.tar.gz, or valdr-sovereign.valdr-pack.tar.gz.
2. For durable workflows, use Sovereign and also download valdr-workflow.valdr-pack.tar.gz from the latest Workflow pack release.
3. Import the core archive first, then the Workflow archive if you use it.

Import generated archives directly. Valdr does not discover pack source from repository or user-wide directories. Keep source checkouts only when authoring a pack.

User-tools compatibility

Use the latest Valdr CLI release both where you build user-tool packs and on the workflow host that runs them. Older clients may reject packs that contain user tools.

The valdr-tools starter pack, with language examples and CLI adapters, is separate from the core and Workflow packs. See Use the Starter Pack to build it and User Tools to run your first tool. You manage runtimes, dependencies, CLI versions, and sign-ins on your own machine.

What’s in the pack

The core pack provides the general agent roster and shared capabilities. The separate Workflow pack adds Verdandi, workflow-owned agents, and saved workflow definitions. Import the compatible core pack first so the Workflow pack can resolve its shared Valdr capabilities. See the Valdr Packs guide for details on pack structure and authoring your own.

Import via the UI

You can also import packs through the Valdr UI:

1. Open Settings > Valdr Packs
2. Click Import Pack and select the .valdr-pack.tar.gz archive
3. Review the preflight summary — it shows what will be added and flags any conflicts
4. Confirm the import

You can also import the downloaded files from the command line. This example installs the Sovereign core and Workflow packs:

valdr import-pack valdr-sovereign.valdr-pack.tar.gz
valdr import-pack valdr-workflow.valdr-pack.tar.gz

Existing conflicts are shown without changing anything by default. Re-run with --on-conflict overwrite to apply incoming pack content or --on-conflict skip to preserve existing records.

2. Register providers and create presets

Valdr supports Claude, Codex, OpenCode, and Ollama integrations. Presets are saved launch configurations that pair a provider with a model, runtime settings, and worktree policy. You need at least one provider and one preset before you can launch agents.

Add a provider

1. Open Settings > Providers
2. Click + to add a new provider
3. Fill in the provider details:
   • Display name — what you’ll see in dropdowns (e.g., “Claude Code”)
   • Type — the integration protocol (claude, codex, opencode, or ollama)
   • Default model — an optional suggested model; leave empty for OpenCode
   • Models — optional choices for the model dropdown; OpenCode can use an empty list
4. Set Enabled to Yes
5. Save

Set up OpenCode

Add an enabled OpenCode provider. Leave its API key variable, base URL, default model, and token limit empty, and keep Models as [].

Then create one or more presets. Set the desired model (provider/model) and optionally agent (such as build) in Config JSON. OpenCode handles its own sign-in; Env refs can stay empty. MCP servers are optional. See the OpenCode preset example.

Upgrading from earlier releases: Presets using gemini, openai, or anthropic no longer launch in 0.3.4. Create new OpenCode presets and update affected agent and workflow selections; existing presets are not converted automatically.

Set up environment variables

Some providers need API keys. Presets should reference environment variable names, with values loaded at launch time. OpenCode can use its own saved authentication without a Valdr API-key setting.

Export your keys in your shell profile (e.g., ~/.zshrc):

# Add the keys for providers you use
export ANTHROPIC_API_KEY="sk-ant-..."
export CODEX_API_KEY="..."
export OPENAI_API_KEY="sk-..."

Reload your shell or source the file:

source ~/.zshrc

Restart Valdr and your MCP host from the environment containing those variables. Exporting a key in a new terminal does not change the environment of an already running process. User-tool environment references have their own startup configuration.

Create an agent preset

1. Open Settings > Agent Presets
2. Click + to create a new preset
3. Configure:
   • Key — unique slug like coder-claude or reviewer-codex
   • Provider — select from your registered providers
   • Model — pick a listed model, or set model in Config JSON for OpenCode
   • Env refs — comma-separated variable names the agent needs (e.g., ANTHROPIC_API_KEY)
   • Worktree options — keep “Create worktree by default” checked for branch isolation and easier review
4. Save

You can create multiple presets for different workflows: a coding preset with a powerful model, a review preset with a faster one, a local Ollama preset for offline work. Switch between them per-launch without reconfiguring anything.

Import presets from a provider pack

If your team has shared Provider Packs, you can skip manual setup entirely:

1. Go to Settings > Providers and click Import
2. Load the provider pack — providers, models, and defaults are created automatically
3. Go to Settings > Agent Presets and click Import
4. Load the preset pack — ready-to-use launch configurations appear instantly

This is the fastest path for teams: one person configures, everyone imports.

3. Set up your first project

Projects in Valdr organize tasks, sprints, and agent work under a single umbrella. You need at least one project before you can create tasks and launch agents against them.

1. Open Projects from the sidebar
2. Click New Project
3. Fill in:
   • Name — descriptive project name
   • Key — short, slug-friendly identifier used across the UI and MCP commands (e.g., my-api, webapp-v2)
   • Description — what the project covers
   • Owners — who’s responsible for decisions
4. Set status to In Progress and save

Your project is now ready. Create tasks under it, assign agents, and start running work.

Verify your setup

A quick sanity check that everything is wired up:

1. Packs — Agents appear in the Agents sidebar (orchestrators, executors, reviewers, etc.)
2. Providers — At least one provider shows Enabled: Yes in Settings > Providers
3. Presets — At least one preset appears in Settings > Agent Presets
4. Project — A project exists with status In Progress

If all four check out, you’re ready to launch your first agent.

Recommended defaults

• Start local-only if you’re evaluating — an Ollama provider works offline with no API keys
• Keep worktree creation enabled on presets so agent changes are always isolated
• Use descriptive preset keys — you’ll see them in every session record and they make filtering easy
• Set at least one project owner — reviews and approvals route through ownership

Next steps

Configuration is done. Head to Use Valdr for your first agent run, or jump straight to Launching Agents to put your presets to work.