Install Valdr

Prerequisites

macOS (Apple Silicon / arm64)
Homebrew
Claude Code or Codex pre-installed

Install

brew tap projectviking-ai/valdr https://github.com/projectviking-ai/homebrew-valdr.git
brew install valdr

Verify the CLI is installed:

valdr version

Activate your license

When you sign up for a Valdr subscription, you receive a license key by email. Create the license file Valdr reads at startup:

mkdir -p ~/.valdr
echo "YOUR_LICENSE_KEY_HERE" > ~/.valdr/valdr.lic

Replace YOUR_LICENSE_KEY_HERE with the key from your signup email. Raider (free tier) users receive a license key too — paste it the same way.

Start Valdr

Launch Valdr by pointing it at a data directory and a port for the UI:

valdr --pm-home ~/.valdr/pm --port 7777

You’ll be prompted for a username and password. This is a local authentication layer for your Valdr UI and MCP data — it’s not connected to any external identity provider. Pick any credentials you’ll remember:

Valdr userName: yourname
Valdr password: yourpassword

The Valdr UI opens in your browser at http://localhost:7777.

These credentials protect your agent work from unauthorized access — including from agents that might try to update Valdr data directly. You’ll use the same credentials when configuring your MCP connection.

Configure your MCP host

Valdr gets more useful the moment your MCP host points at the same local workspace. Use the same --pm-home, username, and password you chose above so Claude or Codex can work against your local projects, tasks, sessions, and reviews without any extra sync layer.

Add this block to your Claude MCP config:

{
"mcpServers": {
  "valdr": {
    "type": "stdio",
    "command": "valdr",
    "args": [
      "pm",
      "--pm-home",
      "/Users/<your username>/.valdr/pm"
    ],
    "env": {
      "VALDR_DB_USERNAME": "<your username>",
      "VALDR_DB_PASSWORD": "<yourpassword>"
    }
  }
}
}

Add this block to your Codex MCP config:

[mcp_servers.valdr]
command = "valdr"
args = ["pm", "--pm-home", "/Users/<userdir>/.valdr/pm"]
env = { VALDR_DB_USERNAME = "<username>", VALDR_DB_PASSWORD = "<password>" }

After saving the config, restart your MCP host so it launches valdr pm with the new values.

The --pm-home, VALDR_DB_USERNAME, and VALDR_DB_PASSWORD values must match the Valdr instance you started above. If they do not match, your MCP host will either fail authentication or connect to the wrong local database.

If your Claude config already has an mcpServers object, merge the valdr block into it rather than replacing the whole file.

Choosing a data directory (`--pm-home`)

The --pm-home flag tells Valdr where to store its database — projects, tasks, sprints, sessions, and all platform state. You have two options:

Location	Flag	When to use
Global (recommended)	`--pm-home ~/.valdr/pm`	One database for all your projects. All work lives in a single place regardless of which repo you’re in.
Repo-local	`--pm-home ./.valdr/pm`	A separate database per repository. Data is scoped to the current repo and can travel with it.

Start with global. A single ~/.valdr/pm database keeps all your projects, tasks, and agent history in one place. You can access everything from any repo, the dashboard gives you a unified view, and there’s no risk of losing track of which directory holds which data.

Repo-local (--pm-home ./.valdr/pm) is useful for isolated experiments or when you want a clean separation between projects, but for most workflows a global database is simpler and more practical.

Next steps

Valdr is running. Head to Configure Valdr to install packs, register providers, and set up your first project.

Configure Valdr