# Install Valdr
## Prerequisites

- macOS (Apple Silicon / arm64)
- [Homebrew](https://brew.sh/)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://openai.com/index/introducing-codex/) pre-installed

## Install

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

Verify the CLI is installed:

```bash
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:

```bash
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:

```bash
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:

```bash
Valdr userName: yourname
Valdr password: yourpassword
```

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

{{< callout type="info" >}}
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.
{{< /callout >}}

---

## 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.

{{< tabs >}}
  {{< tab name="Claude" selected=true >}}

Add this block to your Claude MCP config:

```json
{
  "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>"
      }
    }
  }
}
```

  {{< /tab >}}
  {{< tab name="Codex" >}}

Add this block to your Codex MCP config:

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

  {{< /tab >}}
{{< /tabs >}}

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

{{< callout type="warning" >}}
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.
{{< /callout >}}

{{< callout type="info" >}}
If your Claude config already has an `mcpServers` object, merge the `valdr` block into it rather than replacing the whole file.
{{< /callout >}}

---

## 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](/valdr/docs/getting-started/configure/) to install packs, register providers, and set up your first project.