> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valarhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi

> Route Pi through Valar, and what the CLI writes to Pi's ~/.pi/agent config files

ValarCode routes Pi through Valar by registering its own `valar` provider in Pi's config. Pi speaks the Anthropic Messages API, so it works the same way as Claude Code: the gateway maps what Pi sends to the target your routing resolves to. See [Set up ValarCode](/valarcode/setup) for the shared setup and the client-id model.

## Prerequisites

* Pi installed, with a `~/.pi/agent` config directory.
* A Valar coding key (`vlrcode_…`) and the `valar` CLI ([install](/valarcode/setup#install-the-cli)).

## Enable routing

Run once per machine:

```bash theme={"system"}
valar pi on --api-key <your-coding-key>
```

Pi reads its config at startup, so **restart Pi** for the change to take effect. Check the state any time:

```bash theme={"system"}
valar pi status
```

## What gets written

Pi keeps its config in three JSON files under `~/.pi/agent/`. `valar pi on` edits all three, preserving other providers and unrelated keys:

**`settings.json`** makes the `valar` provider active and pins a model from Valar's list:

```json theme={"system"}
{
  "defaultProvider": "valar",
  "defaultModel": "claude-opus-4-8"
}
```

Your current selection is kept when Valar offers that model; otherwise it moves to Valar's default.

**`auth.json`** stores the bare coding key under a Valar-managed entry:

```json theme={"system"}
{
  "valar": {
    "type": "api_key",
    "key": "vlrcode_…",
    "managedBy": "valar"
  }
}
```

**`models.json`** declares the `valar` provider against the gateway, with its model list and the headers that attribute your traffic:

```json theme={"system"}
{
  "providers": {
    "valar": {
      "name": "Valar",
      "baseUrl": "https://api.valarhq.ai",
      "api": "anthropic-messages",
      "compat": { "sendSessionAffinityHeaders": true },
      "headers": {
        "X-Valar-Client-Id": "jdoe",
        "X-Valar-Harness": "pi",
        "X-Valar-Cli-Version": "1.4.2"
      },
      "models": [ … ]
    }
  }
}
```

Each entry in `models` carries one model's id, display name, context window, max output tokens, cost, and whether it accepts images. The array is the whole catalog for this provider — it is exactly what Pi's model picker offers. Your own builtin `anthropic` provider is left alone, still pointed at `api.anthropic.com`.

Pi's Anthropic SDK appends `/v1/messages`, so a trailing `/v1` on the base URL is stripped before it is written. All three files are written user-only (`0600`), since they hold the key and the client-id header. Before the first change, the originals are snapshotted to `~/.valar/pi/backup.json`, so `off` restores them byte-for-byte.

<Note>
  The client id defaults to your OS username, so the header reads `X-Valar-Client-Id: jdoe`. Use `--user-id RANDOM` for an opaque `vc_…` id instead. See [per-engineer attribution](/valarcode/setup#per-engineer-attribution).
</Note>

## Turn off routing

```bash theme={"system"}
valar pi off
```

This restores the three pre-enable files. Restart Pi for the change to take effect.

## Next steps

<CardGroup cols={2}>
  <Card title="Model routing" icon="route" href="/valarcode/routing">
    How cohorts and the split decide which model serves each request.
  </Card>

  <Card title="LiteLLM integration" icon="diagram-project" href="/valarcode/litellm">
    Pi works through a LiteLLM proxy the same way Claude Code does.
  </Card>
</CardGroup>