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

# TrueFoundry integration

> Run ValarCode through the TrueFoundry AI Gateway so Claude Code's per-engineer client id and routing still reach Valar

If you already run the [TrueFoundry AI Gateway](https://www.truefoundry.com/docs/ai-gateway/quick-start), you can keep it and still use ValarCode. Claude Code points at TrueFoundry, TrueFoundry forwards to Valar, and Valar's per-engineer routing and attribution work as long as the client id makes it through.

This page covers Claude Code and **Pi**. Both send the client id in an `X-Valar-Client-Id` header, so the gateway setup is shared; only the last step, [connecting the tool](#connect-claude-code), differs.

## How it fits together

```mermaid theme={"system"}
flowchart LR
  CC["Claude Code"] -->|"X-Valar-* headers"| T["TrueFoundry AI Gateway"]
  T -->|"x-tfy-forward-headers allowlist"| V["Valar gateway"]
  V --> RT["Route request<br/>Valar Auto picks the target model"]
  RT --> MS["Valar model serving"]
```

`valar claude on` writes three Valar headers into `~/.claude/settings.json`: `X-Valar-Client-Id` (attributes usage to an engineer, defaulting to their username), `X-Valar-Harness` (names the tool, from a fixed set of supported values) and `X-Valar-Cli-Version`. TrueFoundry makes its own request upstream, so these headers are the only reliable signal Valar has about who and what is calling.

TrueFoundry reaches Valar as an **Anthropic** provider account with a custom Base URL. Three settings matter:

1. The Base URL must include `/v1`.
2. Claude Code and Pi send model names with no account prefix, and TrueFoundry addresses models as `account/model`, so each name they send needs a virtual-model **slug**.
3. TrueFoundry copies a client header upstream only when the request names it in `x-tfy-forward-headers`.

## Add Valar as a provider account

**AI Gateway → Models → Add Model → To New Provider Account → Anthropic.**

| Field | Value |
| - | - |
| Name | `valar` |
| Anthropic API Key | your Valar coding key (`vlrcode_…`) |
| Base URL (advanced settings) | `https://api.valarhq.ai/v1` |

TrueFoundry stores the key and authenticates to Valar upstream, so the coding key never reaches engineers' machines.

> [!WARNING]
>
> The Base URL must include `/v1`. TrueFoundry appends only the endpoint path (`/messages`), so the bare root returns 404 on every request. This is the same convention as Portkey and the opposite of LiteLLM.

Then add these models to the account with **Add Model Manually**. Use the same value for the model name and the model ID:

| Model name and ID | Used for |
| - | - |
| `valar-auto` | Valar Auto, the default for Claude Code and Pi |
| `claude-opus-5-5` | Claude Code requests that name a Claude model |
| `claude-sonnet-5-5` | Same |
| `claude-haiku-5-5` | Same |
| `claude-fable-5-2` | Same |

Valar maps Claude model names onto the model the engineer's routing resolves to, so the Claude names need no counterpart in the Valar catalog.

Create this account in the UI. The Base URL is what points the account at Valar, and without it TrueFoundry sends requests to Anthropic. If you manage TrueFoundry with `tfy apply`, save the account in the UI first, then click **Apply using YAML** and commit the manifest it exports, so the Base URL is part of it.

To call specific Valar models, list the ids your coding key can reach and add each `data[].id` as a model ID, preserving spelling and case. Skip ids served only on Valar's OpenAI-compatible APIs; they have no route on the Anthropic Messages API.

```bash theme={"system"}
curl https://api.valarhq.ai/v1/models -H "Authorization: Bearer <valar-coding-key>"
```

TrueFoundry does not allow `/` in a model name, so give those a flat name (for example name `glm-5-3`, model ID `zai-org/GLM-5.3`). Callers address it as `valar/glm-5-3`.

## Map the model names the tools send

TrueFoundry does not serve Valar's model list, so `valar claude on` and `valar pi on` offer **Valar Auto** alone and say so when you run them. Valar then picks the model for each request. The names that reach TrueFoundry are:

| Sent by | Model name |
| - | - |
| Claude Code, for the Valar Auto row in its picker | `anthropic.valar-auto` |
| Pi | `valar-auto` |
| Claude Code, for background requests and subagents | `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-2` |

None of them carries the `valar/` account prefix. A virtual model with a slug lets TrueFoundry accept each name as sent and route it to the `valar` account.

```yaml valar-virtual-models.yaml theme={"system"}
name: valar-claude
type: provider-account/virtual-model
collaborators:
  - subject: user:<admin-email>
    role_id: provider-account-manager
  - subject: team:<valar-pilot-team>
    role_id: provider-account-access
integrations:
  - type: integration/model/virtual
    name: valar-auto-claude-code
    slug: anthropic.valar-auto
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/valar-auto
          priority: 0
  - type: integration/model/virtual
    name: valar-auto
    slug: valar-auto
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/valar-auto
          priority: 0
  - type: integration/model/virtual
    name: claude-opus-5-5
    slug: claude-opus-5-5
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/claude-opus-5-5
          priority: 0
  - type: integration/model/virtual
    name: claude-sonnet-5-5
    slug: claude-sonnet-5-5
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/claude-sonnet-5-5
          priority: 0
  - type: integration/model/virtual
    name: claude-haiku-5-5
    slug: claude-haiku-5-5
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/claude-haiku-5-5
          priority: 0
  - type: integration/model/virtual
    name: claude-fable-5-2
    slug: claude-fable-5-2
    model_types: [chat]
    routing_config:
      type: priority-based-routing
      load_balance_targets:
        - target: valar/claude-fable-5-2
          priority: 0
```

```bash theme={"system"}
tfy apply -f valar-virtual-models.yaml
```

* Both Auto slugs target `valar/valar-auto`, so Valar receives `valar-auto` whichever tool sent the request.
* The four Claude names are what Claude Code currently sends for its Opus, Sonnet, Haiku and Fable tiers. A newer release may add or rename one; the TrueFoundry request log shows what yours sends. A name with no slug is refused by the gateway.
* No fallback target is configured. Add one only if you want traffic to leave Valar when Valar errors.

> [!WARNING]
>
> Slugs are unique across the whole tenant. Once `valar-claude` owns `claude-sonnet-5-5`, every request for that name from a key with access to this group goes to Valar, on Valar's bill. Grant `provider-account-access` on `valar-claude` and `valar` only to the engineers who should use Valar. Other callers keep using `account/model` ids.

### Alternative: pin prefixed model names instead of slugs

To run Claude Code on its Claude tiers without `valar claude on`, skip the virtual models and set, in a managed settings file:

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "valar/claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "valar/claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "valar/claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "valar/claude-fable-5-2"
  }
}
```

`valar claude on` removes these variables and pins Valar Auto, so this variant does not go through the CLI. Set `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` and the headers below by hand.

## Generate a TrueFoundry API key

Create a personal access token or virtual account key with access to `valar-claude` and `valar`. Claude Code and Pi use it as their bearer token.

* The tool authenticates to TrueFoundry with the TrueFoundry key.
* TrueFoundry authenticates to Valar with the stored coding key.

## Connect Claude Code

```bash theme={"system"}
valar claude on --direct --endpoint https://gateway.truefoundry.ai --api-key <truefoundry-api-key>
```

`--direct` makes Claude Code call the endpoint itself. Without it, the CLI can route Claude Code through Valar's on-device proxy instead, and then `settings.json` carries no `ANTHROPIC_BASE_URL`, token or Valar headers for TrueFoundry to receive. Keep the flag every time you re-run the command.

On a self-hosted gateway the endpoint ends at `/api/llm`, not `/api/llm/v1`; copy the host from the Playground's Code Snippet tab.

Then add the forward list to `ANTHROPIC_CUSTOM_HEADERS` in `~/.claude/settings.json`:

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.truefoundry.ai",
    "ANTHROPIC_AUTH_TOKEN": "<truefoundry-api-key>",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Valar-Client-Id: jdoe\nX-Valar-Harness: claude\nX-Valar-Cli-Version: 1.4.2\nx-tfy-forward-headers: [\"x-valar-client-id\",\"x-valar-harness\",\"x-valar-cli-version\",\"anthropic-beta\"]"
  }
}
```

* `x-tfy-forward-headers` is a JSON array of header names. TrueFoundry copies each named header onto the upstream request; without it Valar receives none of them.
* `valar claude on` rewrites only its own three `X-Valar-*` lines and preserves other headers, so the order of operations does not matter.
* `anthropic-beta` is in the list because Claude Code uses Anthropic beta features that fail closed when the header is dropped.
* Do not set `x-tfy-anthropic-beta` or `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`. TrueFoundry's generic Claude Code guide includes both, but `x-tfy-anthropic-beta` replaces Claude Code's own beta list with a fixed one.
* Do not set `ANTHROPIC_DEFAULT_*_MODEL` (unless you chose the [alternative](#alternative-pin-prefixed-model-names-instead-of-slugs) above). `/model` shows one row, Valar Auto, and Valar picks the model for each request.

A missing `X-Valar-Client-Id` fails silently: requests return 200 but usage is unattributed. A missing `X-Valar-Harness` is recorded as Claude Code.

## Connect Pi

```bash theme={"system"}
valar pi on --endpoint https://gateway.truefoundry.ai --api-key <truefoundry-api-key>
```

`valar pi on` writes the Valar headers to the `valar` provider in `~/.pi/agent/models.json`. Add the forward list beside them, then restart Pi:

```json theme={"system"}
{
  "providers": {
    "valar": {
      "headers": {
        "X-Valar-Client-Id": "jdoe",
        "X-Valar-Harness": "pi",
        "X-Valar-Cli-Version": "1.4.2",
        "x-tfy-forward-headers": "[\"x-valar-client-id\",\"x-valar-harness\",\"x-valar-cli-version\",\"anthropic-beta\"]"
      }
    }
  }
}
```

The list matches Claude Code's, including `anthropic-beta`, so any beta features Pi requests reach Valar. Leave the rest of the `valar` provider as the CLI wrote it. `valar pi on` rewrites only its own three headers and preserves the others, so the line survives a re-run. Without it, Pi's requests succeed but arrive at Valar unattributed and are recorded as Claude Code.

## Verify it works

After the first few requests, check:

* **TrueFoundry request logs:** the request resolves to `valar/<model>` (also in the `x-tfy-resolved-model` response header) and succeeds. The trace attribute `tfy.model.anthropic_betas_sent` shows the betas forwarded.
* **Valar analytics dashboard:** the engineer appears under their client id, and their harness list includes the tool you connected (`claude` or `pi`).
* If usage is unattributed, check the `x-tfy-forward-headers` line first; a missing or misspelled name is the usual cause.
* If every request returns 404, the Base URL is missing `/v1`.
* If a request returns 403 "not authorized to access model … or model does not exist", the model name has no slug or the key lacks access to `valar-claude`. For `anthropic.valar-auto` or `valar-auto`, check the two Auto slugs.

To stop routing through TrueFoundry and restore the tool's previous settings:

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

`off` reverts only the settings the CLI wrote and leaves everything else in place, so the forward list you added can remain. After `valar claude off`, open `~/.claude/settings.json` and delete the `x-tfy-forward-headers` line from `ANTHROPIC_CUSTOM_HEADERS` if it is still there; remove the variable if that leaves it empty. After `valar pi off`, do the same for `x-tfy-forward-headers` under the `valar` provider in `~/.pi/agent/models.json`, if that provider is still present.

## Next steps

> [card] [Claude Code](https://docs.valarhq.ai/valarcode/claude-code.md)
>
> The direct connect path and what the CLI writes to `settings.json`.

> [card] [Portkey](https://docs.valarhq.ai/valarcode/portkey.md)
>
> The same setup for a Portkey gateway.

> [card] [Model routing](https://docs.valarhq.ai/valarcode/routing.md)
>
> How the client id drives cohort assignment and the split.

> [card] [Analytics](https://docs.valarhq.ai/valarcode/analytics.md)
>
> Where per-engineer attribution shows up.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.