Skip to main content
If you already run the TrueFoundry AI Gateway, 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, differs.

How it fits together

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. TrueFoundry stores the key and authenticates to Valar upstream, so the coding key never reaches engineers’ machines.
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: 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.
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: 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.
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.
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:
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

--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:
  • 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 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

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

Claude Code

The direct connect path and what the CLI writes to settings.json.

Portkey

The same setup for a Portkey gateway.

Model routing

How the client id drives cohort assignment and the split.

Analytics

Where per-engineer attribution shows up.