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:
- The Base URL must include
/v1. - 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. - 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.
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.
/ 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, sovalar 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 receivesvalar-autowhichever 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.
Alternative: pin prefixed model names instead of slugs
To run Claude Code on its Claude tiers withoutvalar 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 tovalar-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-headersis a JSON array of header names. TrueFoundry copies each named header onto the upstream request; without it Valar receives none of them.valar claude onrewrites only its own threeX-Valar-*lines and preserves other headers, so the order of operations does not matter.anthropic-betais in the list because Claude Code uses Anthropic beta features that fail closed when the header is dropped.- Do not set
x-tfy-anthropic-betaorCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. TrueFoundry’s generic Claude Code guide includes both, butx-tfy-anthropic-betareplaces Claude Code’s own beta list with a fixed one. - Do not set
ANTHROPIC_DEFAULT_*_MODEL(unless you chose the alternative above)./modelshows one row, Valar Auto, and Valar picks the model for each request.
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:
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 thex-tfy-resolved-modelresponse header) and succeeds. The trace attributetfy.model.anthropic_betas_sentshows the betas forwarded. - Valar analytics dashboard: the engineer appears under their client id, and their harness list includes the tool you connected (
claudeorpi). - If usage is unattributed, check the
x-tfy-forward-headersline 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. Foranthropic.valar-autoorvalar-auto, check the two Auto slugs.
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.