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)
• Registering AI providers and creating agent presets
• Setting up your first project

1. Install Valdr Packs

Valdr packs bundle agents, prompts, and capabilities into portable archives. The default pack ships with pre-built agents for orchestration, planning, execution, review, and auditing — so you’re productive immediately.

Download the latest packs

Official Valdr packs are published as releases on GitHub:

1. Go to projectviking-ai/valdr-packs
2. Download the latest release archive

Unpack into your repo

Unpack the archive into your local repository so packs travel with your codebase:

# From your repo root — recommended location
mkdir -p .valdr/valdr-packs
tar -xzf valdr-pack-*.tar.gz -C .valdr/valdr-packs/

Or place them in a top-level valdr-packs/ directory in your repo:

mkdir -p valdr-packs
tar -xzf valdr-pack-*.tar.gz -C valdr-packs/

Valdr discovers packs in both locations. Keeping them in-repo means every collaborator gets the same agents, prompts, and capabilities when they clone.

Where Valdr looks for packs

What’s in the pack

After unpacking, you’ll have the full agent roster: orchestrators, planners, executors, reviewers, and auditors — plus shared prompts and 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

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 to run your first workflow, or jump straight to Launching Agents to put your presets to work.