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 this exact compatible set:

Open the Valdr Packs releases page, then:

1. Download valdr-sovereign.valdr-pack.tar.gz from v0.3.0.
2. Download valdr-workflow.valdr-pack.tar.gz from valdr-workflow-v0.13.0.
3. Import Sovereign first, then Workflow.

The matching macOS CLI release is v0.3.0 on the Valdr Releases page, with valdr-v0.3.0-macos-arm64.tar.gz and its .sha256 file.

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

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:

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

Providers are the AI backends Valdr talks to — Claude, Codex, Ollama, and others. 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, ollama, etc.)
   • Default model — the model used when none is specified
   • Models — register the models available through this provider
4. Set Enabled to Yes
5. Save

Set up environment variables

Some providers need API keys. Valdr never stores secrets directly — presets reference environment variable names, and values are loaded from your shell environment at launch time.

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

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 model from that provider
   • 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.