Claude Code at NVIDIA's Free Model Catalog. It Took a Proxy and Four Traps.
Claude Code only speaks Anthropic's Messages API. NVIDIA's hosted catalog at build.nvidia.com — free, no credit card, dozens of models — only speaks OpenAI chat-completions. Those two facts don't meet in the middle on their own. Here's the proxy that bridges them, a real /v1/models call to see what's actually on the shelf, and the four traps that will burn an afternoon if nobody warns you first.
Why bother with another backend
I've written before about running Claude Code against Ollama Cloud to get GLM and Kimi behind the same tooling for twenty bucks a month. NVIDIA's build.nvidia.com catalog is a different animal worth adding to the same rotation: it's free, it doesn't ask for a card, and the model list leans toward the NVIDIA-tuned Nemotron family plus a rotating cast of open-weight models — Kimi, GPT-OSS, and others — hosted on NVIDIA's own infrastructure. Sign up with the NVIDIA Developer Program, generate an API key, and you've got a bearer token against real inference with nothing charged to anything.
The catch is the shape of the API. Claude Code was built to talk to Anthropic's Messages API. NVIDIA's NIM endpoints speak OpenAI's chat-completions shape. Same idea — send messages, get a completion — different field names, different request structure. Claude Code doesn't know how to speak NVIDIA's dialect, and NVIDIA's validator doesn't know what to do with half of what Claude Code sends. You need a translator sitting in between, and once you add one, a few sharp edges show up that aren't obvious until you hit them.
The pieces
| Piece | Role |
|---|---|
| claude-code-router (ccr) | Local daemon that speaks Anthropic's Messages API on one side and OpenAI chat-completions on the other |
| NVIDIA API key | From build.nvidia.com, used as a bearer token against integrate.api.nvidia.com |
| A small request-shape fixup | NVIDIA validates request bodies strictly and rejects fields Claude Code sends by default |
| A profile wrapper (optional, recommended) | Isolates config, trust state, and history per backend so NVIDIA doesn't tangle with your normal Claude install or your Ollama one |
1. Install and start ccr
npm install -g @musistudio/claude-code-router # verify the current package name on npm
ccr startccr listens on 127.0.0.1:3456 by default and proxies Anthropic-shaped requests out to whatever providers you configure.
2. Point it at NVIDIA
Edit ~/.claude-code-router/config.json:
{
"Providers": [
{
"name": "nvidia",
"api_base_url": "https://integrate.api.nvidia.com/v1/chat/completions",
"api_key": "$NVIDIA_API_KEY",
"models": [
"moonshotai/kimi-k3",
"nvidia/nemotron-3.5-lightning-30b-a3b",
"openai/gpt-oss-20b"
],
"transformer": {
"use": ["nvidia-strip-unsupported"]
}
}
],
"Router": {
"default": "nvidia,moonshotai/kimi-k3"
}
}Two things worth calling out before you move on:
api_key: "$NVIDIA_API_KEY"— ccr interpolates environment variables in the config at request time. The key never sits in the file in plaintext; it just has to be present in the environment of the process that starts ccr.- The
modelslist is a gate, not a hint. If a model isn't listed here, ccr quietly falls through to theRouterdefault instead of calling it — see Trap #2 below. This bit me before I understood it.
3. Trap #1 — NVIDIA rejects Claude Code's thinking params
Claude Code sends a thinking block on nearly every turn. ccr's default transformer maps that onto an OpenAI-style reasoning parameter. NVIDIA's NIM validator rejects any parameter a given model hasn't explicitly declared support for:
HTTP 400 {"message":"Validation: Unsupported parameter(s): `reasoning`"}Since Claude Code thinks on almost every request, this isn't an edge case — it kills the session on the first prompt. The bundled cerebras transformer that ships with ccr isn't a fix either: when the reasoning key is absent, it substitutes disable_reasoning: false, which several NVIDIA models reject just as hard.
Fix: a small custom ccr transformer plugin that strips the offending keys before the request leaves the box.
~/.claude-code-router/plugins/nvidia-strip-unsupported.js:
class NvidiaStripUnsupported {
constructor(options = {}) {
this.name = "nvidia-strip-unsupported";
this.options = options || {};
this.strip = this.options.strip ||
["reasoning", "disable_reasoning", "thinking", "enable_thinking"];
this.keepReasoningFor = new Set(this.options.keepReasoningFor || []);
}
async transformRequestIn(request) {
const body = { ...request };
const exempt = this.keepReasoningFor.has(body.model);
for (const key of this.strip) {
if (!(key in body)) continue;
if (exempt && (key === "reasoning" || key === "thinking")) continue;
delete body[key];
}
return body;
}
async transformResponseOut(response) {
return response;
}
}
module.exports = NvidiaStripUnsupported;Reference it from the provider's transformer.use list, as shown in step 2. You lose the thinking-budget hint for models that can't take it — a much cheaper cost than a dead session.
4. Trap #2 — bare model names silently fall through to the wrong provider
ccr only does a direct provider lookup when the model string contains a comma — its router checks for model.includes(","). A bare name like moonshotai/kimi-k3 doesn't match that, so it falls through to whatever Router.default is configured — which may be a different provider entirely if you're already running Ollama Cloud or OpenRouter through the same daemon. You will not get an error. You will just silently bill, and get answers from, the wrong backend.
Fix: always pass the provider-qualified form, nvidia,<model>:
claude --model nvidia,moonshotai/kimi-k3
# or mid-session:
/model nvidia,openai/gpt-oss-20bIf you want to keep typing bare model names on the CLI, wrap the invocation in a shell function that rewrites --model X to --model nvidia,X whenever the value doesn't already contain a comma. The profile script below does exactly that.
5. Trap #3 — the model also has to be in ccr's per-provider models[]
Separate from trap #2: even with the nvidia, prefix, if the model string isn't present in that provider's models array in config.json, ccr still falls back to the Router default instead of erroring. Keep that array current — NVIDIA's catalog changes, and retired model IDs get real deadlines: advance notice, then the ID starts 400/410ing. Re-check it against /v1/models (next section) periodically rather than trusting a list you wrote once.
6. See what's actually on the shelf: the /v1/models call
Before wiring anything into Claude Code, hit NVIDIA directly and get the real, current catalog — not a blog post's memory of it:
curl -sS https://integrate.api.nvidia.com/v1/models \
-H "Authorization: Bearer $NVIDIA_API_KEY" | jq .It comes back in the same OpenAI-compatible shape as /v1/chat/completions expects for the model field — a flat list with id, object, created, and owned_by. This is a real excerpt, pulled live against my own key while writing this:
{
"object": "list",
"data": [
{
"id": "deepseek-ai/deepseek-coder-6.7b-instruct",
"object": "model",
"created": 735790403,
"owned_by": "deepseek-ai"
},
{
"id": "deepseek-ai/deepseek-v4.1-flash",
"object": "model",
"created": 735790403,
"owned_by": "deepseek-ai"
},
{
"id": "moonshotai/kimi-k3",
"object": "model",
"created": 735790403,
"owned_by": "moonshotai"
},
{
"id": "nvidia/llama-3.1-nemotron-70b-instruct",
"object": "model",
"created": 735790403,
"owned_by": "nvidia"
},
{
"id": "nvidia/nemotron-3-ultra-550b-a55b",
"object": "model",
"created": 735790403,
"owned_by": "nvidia"
},
{
"id": "openai/gpt-oss-20b",
"object": "model",
"created": 735790403,
"owned_by": "openai"
},
{
"id": "z-ai/glm-5.3",
"object": "model",
"created": 735790403,
"owned_by": "z-ai"
},
{
"id": "z-ai/glm-5.3-flash",
"object": "model",
"created": 735790403,
"owned_by": "z-ai"
}
]
}Notice created is identical — 735790403, which decodes to April 1993 — on every single one of the 80 models my key could see, not just these eight. That's not a copy-paste artifact in this post; it's the API itself. NVIDIA doesn't populate real per-model creation dates on this field, so don't use created to judge how new a model is — it's always the same placeholder epoch, for everything.
Filter it down to just the IDs when you're updating ccr's models[] array:
curl -sS https://integrate.api.nvidia.com/v1/models \
-H "Authorization: Bearer $NVIDIA_API_KEY" | jq -r '.data[].id' | sortDo this before you copy anyone's model list into your own config — including the one in this post. The catalog is not static; NVIDIA adds and retires IDs on its own schedule, and the only authoritative source is the endpoint itself.
7. What "free tier" actually means here
Worth being precise, because older write-ups about this catalog will mislead you. At 2024 launch, signups got roughly 1,000 API credits (one credit ≈ one call, not one token), extendable to 5,000 with a business email — that system was phased out by early 2025 in favor of a straight requests-per-minute ceiling, no balance, no card. Generate a key at build.nvidia.com and you're gated by RPM, not tokens or credits.
The ~40 RPM figure that gets quoted around applies per account key, not per model — it doesn't multiply when you add more models to the same key — and there's no self-serve way to raise it; the only path past it is self-hosting the NIM or NVIDIA AI Enterprise. You can watch developers hit that exact wall in NVIDIA's own forums (one thread, a second), since there's no single published limits page — the real number for your account is on your own dashboard. Check it live; don't trust a number here or anywhere else.
What that buys you: a lab, not a production backend. Right for "drive Claude Code without paying frontier rates" or "check a benchmark myself" — the same instinct behind the Ollama Cloud setup — not for paying-customer traffic.
How that stacks up against Groq's free tier
NVIDIA isn't the only free, no-card lab sandbox. Groq runs the same deal on different terms. Check your own numbers at console.groq.com/settings/limits or the community forum; these are the published numbers for its GPT-OSS-class free models:
| NVIDIA build.nvidia.com | Groq (gpt-oss-class free models) | |
|---|---|---|
| Cost | $0, no card | $0, no card |
| Throttle shape | ~40 requests/min, per account key, shared across whatever models you call | 30 requests/min, 8,000 tokens/min, 1,000 requests/day, 200,000 tokens/day — per model |
| Self-serve increase | None on the free tier | None on the free tier |
| Catalog size | ~80 models at last count (section 6), including NVIDIA's own Nemotron line | A much smaller curated set of open models |
| Production use | Not permitted on the free key — deploy the NIM yourself or buy AI Enterprise | Rate-limited, but it's the same real API you'd pay for at higher tiers |
Neither is a free production API. NVIDIA wins on model quality — one key, frontier-class models (Kimi K3, GLM-5.3, Nemotron, DeepSeek) instead of Groq's smaller set. Groq wins if you want a ceiling that resets at midnight instead of a request-rate wall that's always just there. Pick based on which matters more for what you're building.
8. Set the environment and point Claude Code at ccr, not NVIDIA directly
export NVIDIA_API_KEY="nvapi-..." # from build.nvidia.com
export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export ANTHROPIC_AUTH_TOKEN="dummy" # ccr doesn't check this; Claude Code requires it set
export ANTHROPIC_API_KEY="" # must be empty, or Claude Code prefers it over AUTH_TOKEN
export ANTHROPIC_MODEL="nvidia,moonshotai/kimi-k3"
export ANTHROPIC_SMALL_FAST_MODEL="nvidia,nvidia/nemotron-3.5-lightning-30b-a3b"
claudeANTHROPIC_BASE_URL pointing at localhost is correct and intentional — the real outbound call to NVIDIA is made by ccr, using NVIDIA_API_KEY from its own environment. Claude Code itself never talks to NVIDIA directly.
Also worth setting, since Claude Code doesn't know third-party context windows and will otherwise assume 200k and warn about it:
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=128000 # NVIDIA's /v1/models doesn't expose this; treat it as an estimate9. Isolate it as a profile
Running multiple backends — NVIDIA, Ollama Cloud, OpenRouter — out of the same ~/.claude config directory gets confusing fast: history, trust state, and MCP config all mix together. A small wrapper that sources a per-backend env file into an isolated CLAUDE_CONFIG_DIR keeps them from stepping on each other:
~/bin/claude-profile:
#!/usr/bin/env bash
set -euo pipefail
PROFILE_DIR="${CLAUDE_PROFILE_DIR:-$HOME/.claude-profiles}"
name=$1; shift
env_file="$PROFILE_DIR/$name.env"
[[ -r $env_file ]] || { echo "no such profile: $name" >&2; exit 1; }
set -a; source "$env_file"; set +a
: "${CLAUDE_CONFIG_DIR:?profile '$name' did not set CLAUDE_CONFIG_DIR}"
mkdir -p "$CLAUDE_CONFIG_DIR"
exec claude "$@"~/.claude-profiles/nvidia.env:
: "${NVIDIA_API_KEY:?NVIDIA_API_KEY not set}"
# Make sure ccr is actually running before Claude Code tries to talk to it.
if ! (exec 3<>/dev/tcp/127.0.0.1/3456) 2>/dev/null; then
nohup ccr start >/tmp/ccr-start.log 2>&1 &
for _ in $(seq 1 15); do
sleep 1
(exec 3<>/dev/tcp/127.0.0.1/3456) 2>/dev/null && break
done
fi
# Close the bare-model-name trap (#2) automatically.
_ccr_fix_model_args() {
local -a out=(); local n=$#; local i=1
while (( i <= n )); do
local a=${!i}
case $a in
--model)
local j=$((i+1))
if (( j <= n )); then
local v=${!j}
[[ $v == *,* ]] || v="nvidia,$v"
out+=("$a" "$v"); i=$((i+2)); continue
fi ;;
--model=*)
local v=${a#--model=}
[[ $v == *,* ]] || v="nvidia,$v"
out+=("--model=$v"); i=$((i+1)); continue ;;
esac
out+=("$a"); i=$((i+1))
done
printf '%s\0' "${out[@]}"
}
if (( $# )); then
_ccr_argv=()
while IFS= read -r -d '' a; do _ccr_argv+=("$a"); done < <(_ccr_fix_model_args "$@")
set -- "${_ccr_argv[@]}"
fi
unset -f _ccr_fix_model_args
CLAUDE_CONFIG_DIR=$HOME/.claude-nvidia
ANTHROPIC_BASE_URL=http://127.0.0.1:3456
ANTHROPIC_AUTH_TOKEN=dummy
ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=nvidia,moonshotai/kimi-k3
ANTHROPIC_SMALL_FAST_MODEL=nvidia,nvidia/nemotron-3.5-lightning-30b-a3b
CLAUDE_CODE_MAX_CONTEXT_TOKENS=128000alias claude-nvidia='claude-profile nvidia'Then:
claude-nvidia --model moonshotai/kimi-k3 -p "say hi"Trap #4 — each profile has its own workspace-trust store
Not NVIDIA-specific, but it will absolutely make a correctly wired-up profile look broken: CLAUDE_CONFIG_DIR isolation means each profile tracks workspace trust separately, per working directory, in its own .claude.json. Trusting a directory under your normal claude or your claude-ollama profile does not carry over to claude-nvidia — it's a different config dir with a blank trust table.
Symptom:
Ignoring N permissions.allow entries from .claude/settings.json:
this workspace has not been trusted.When that fires, your permissions allowlist is silently ignored and tool calls get gated — which looks exactly like "the model/provider is broken," especially for an agentic model that calls tools on almost every turn.
Fix: run the profile interactively once in that directory and accept the trust dialog, or set it directly (back the file up first — it's hand-editable JSON, not a stable schema):
python3 -c "
import json
path = '$HOME/.claude-nvidia/.claude.json'
d = json.load(open(path))
d['projects']['$PWD']['hasTrustDialogAccepted'] = True
json.dump(d, open(path, 'w'), indent=2)
"10. Verify end to end
Skip Claude Code for a moment and confirm NVIDIA itself is answering:
curl -sS https://integrate.api.nvidia.com/v1/chat/completions \
-H "Authorization: Bearer $NVIDIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"moonshotai/kimi-k3","messages":[{"role":"user","content":"say hi in 3 words"}],"max_tokens":20}'A 200 with a choices[0].message.content means NVIDIA and the key are fine and any remaining problem is in ccr or Claude Code's config, not the provider. Then run the full path and check for a clean result with "is_error": false:
claude-nvidia --model moonshotai/kimi-k3 -p "reply with exactly: PONG" --output-format jsonThree vendors, one call shape, live right now
Same curl, same prompt, same max_tokens, fired at three different vendors' models behind the one NVIDIA endpoint, run live while writing this:
curl -sS https://integrate.api.nvidia.com/v1/chat/completions \
-H "Authorization: Bearer $NVIDIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"moonshotai/kimi-k3","messages":[{"role":"user","content":"Reply with exactly one short sentence: which model are you, in your own words."}],"max_tokens":300}'# Kimi (Moonshot AI) — HTTP 200
"content": "I’m Kimi, an AI assistant developed by Moonshot AI."curl -sS https://integrate.api.nvidia.com/v1/chat/completions \
-H "Authorization: Bearer $NVIDIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"z-ai/glm-5.3","messages":[{"role":"user","content":"Reply with exactly one short sentence: which model are you, in your own words."}],"max_tokens":300}'# GLM (Z.ai) — HTTP 200
"content": "I am GLM, a large language model developed by Z.ai."Both clean, finish_reason: "stop", real content. DeepSeek didn't make it in either form I tried — full results in the table below. Listed in /v1/models isn't the same claim as callable right now, which is the entire reason to run the probe before trusting a model list, including this one.
Known-good / known-bad models, as of testing
Catalogs here churn — re-run the /v1/models call from section 6 before trusting this table in a post written more than a few weeks after you read it.
| Model | Status |
|---|---|
moonshotai/kimi-k3 | Works, including tool calls. NVIDIA rate-limits it harder than most; can be slow (~2–110s observed, highly variable) |
z-ai/glm-5.3 | Works, clean stop finish on a plain chat call |
deepseek-ai/deepseek-v4.1-flash | Listed in /v1/models, but timed out on two separate live attempts (one 504, one 90s client timeout) — not usable as of testing |
deepseek-ai/deepseek-coder-6.7b-instruct | Listed in /v1/models, but the chat-completions call itself 404'd — present in the catalog, not actually callable |
poolside/laguna-xs-2.1 | Works |
nvidia/nemotron-3.5-lightning-30b-a3b | Works, fastest of the set |
nvidia/nemotron-3-ultra-550b-a55b | Works, slow cold start (~45s+) |
openai/gpt-oss-20b | Works |
meta/llama-3.2-90b-vision-instruct | Times out past ~120s |
google/gemma-4-31b-it | Answers bare chat in ~120s but times out once tools are attached (Claude Code always attaches tools) |
| IDs not in NVIDIA's current catalog | 404, not a transient failure — don't retry, re-check the catalog |
| Deprecated/retired IDs | 410 Gone once NVIDIA's end-of-life date passes — drop them from models[] immediately, they won't come back |
The failure modes, for the TL;DR crowd
- 400 "Unsupported parameter(s):
reasoning" → stripthinking/reasoningparams with a custom ccr transformer before they reach NVIDIA. - Silently billing/answering from the wrong provider → always use the comma-qualified
provider,modelform; ccr's router keys off the comma. - Falls back to Router default with no error → the model must also be listed in that provider's
models[]inconfig.json. Verify against/v1/models, don't guess. - "Workspace has not been trusted" / tool calls gated for no apparent reason → each
CLAUDE_CONFIG_DIRprofile has its own trust store; accept the dialog, or patch the flag, per profile, per directory.
Get past those four and NVIDIA's free catalog works in Claude Code like any other backend — full tool-call support, same CLI, same slash commands, just a different $ANTHROPIC_MODEL and nothing on the invoice.
Related reading
- I Kept Paying for One AI Model. Then Ollama Handed Me 37 for Twenty Bucks. — the same bridge pattern, a different free-ish backend
- Beyond Vector Databases: How AI Actually Remembers — the persistent-memory architecture this whole stack runs on
- build.nvidia.com — the live catalog; check it yourself before trusting any model list in a blog post, including this one
- claude-code-router — the proxy that makes any of this possible
