Get going in 30 seconds
export ANTHROPIC_BASE_URL=https://northerninference.ca
export ANTHROPIC_API_KEY=ni_live_YOUR_KEY_HERE
# optional: pin a route from /models so you don't get a model-picker prompt
export ANTHROPIC_MODEL=bedrock/global.anthropic.claude-sonnet-4-6-global
claude
That is everything. Run claude and you are routing through Northern
Inference. Your usage appears in the portal under Usage within
seconds.
How it works
Export both required variables before launching Claude Code.
ANTHROPIC_BASE_URL must be the host root
(https://northerninference.ca, no /v1 suffix). Claude Code
appends /v1/messages itself. Setting /v1 here produces
/v1/v1/messages, which returns a 404.
ANTHROPIC_API_KEY is the only key variable Claude Code reads for
API-key mode; set it directly to your ni_live_... key.
If ANTHROPIC_AUTH_TOKEN is already set in your shell (a direct
Anthropic session token), unset it first: unset ANTHROPIC_AUTH_TOKEN.
A session token overrides API-key mode.
Model selection
Set the model with ANTHROPIC_MODEL before launch, or pass
--model at the command line, or change it inside a running session
with /model:
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global
When ANTHROPIC_BASE_URL points at NI, Claude Code lists models from
NI's /v1/models endpoint. Use full NI route keys from
/models, for example
bedrock/global.anthropic.claude-opus-4-6-v1-global, when you want
explicit residency or provider selection.
If Claude Code sends a model name that is not an exact NI route key, NI returns a numbered list of matching routes. Reply with the number to save that mapping for your account, or paste the full route key shown in the list. The original prompt is not replayed; retry it after confirming the mapping.
Thinking level
Claude Code calls this effort. Set it at launch:
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort low
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort medium
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort high
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort xhigh
claude --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort max
In an active Claude Code session, use /effort to change the
level without restarting.
Extended thinking and --effort are native on Anthropic
(Claude) routes. On a non-Anthropic route (GPT, Gemini, DeepSeek), NI now
converts Claude Code's thinking budget into the portable
reasoning_effort for you, bucketed to low, medium, or high, so
your reasoning request still runs instead of being dropped. That conversion
is coarse, so for exact cross-provider control send
reasoning_effort directly. Routes with no reasoning mode at all
(such as Llama or Mistral) return a normal answer with no reasoning.
One-shot check
claude -p "Reply with NI ok." --model bedrock/global.anthropic.claude-sonnet-4-6-global --effort medium --tools ""The request should appear in portal Usage within a few seconds. The response headers include the NI request ID, resolved route, resolved jurisdiction, and custody path.
Using ni-* commands
When you cannot change the model in your Claude Code config, send an
ni-* command as a prompt. The gateway intercepts it and responds
directly (no model call, no billing).
Useful commands:
ni-models: lists the routes your key can call, numbered.ni-map-model 3: maps your pinned model name to route 3 from that list.ni-map-model <route-id>: maps to an exact route id.ni-unmap: removes the mapping for your current model.ni-status: shows your active model mappings.ni-help: lists all available commands.
Send ni-map-model alone first to get the numbered list, then reply
with ni-map-model <number> to confirm. From that point every
request your harness sends under that pinned name is routed to the route you
chose. Mappings apply to the whole account (all keys). Remove a mapping with
ni-unmap.
When NI returns a numbered list of route choices (for example after sending an ambiguous model name), reply with the number alone to pick that route.
Troubleshooting
Requests do not appear in Usage. Claude Code did not use
the NI endpoint or token from this shell. Check
ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, and that
the variables were exported before claude was launched.
401 from NI. Confirm the token is an NI API key and the
environment variable is ANTHROPIC_API_KEY.
Unknown request parameter: output_config. The gateway is running an older build without Claude Code effort support. Current Claude Code releases use this field for effort.
invalid beta flag. Claude Code sent a client-side
?beta=true signal through a gateway build that forwarded it to
Bedrock. Current gateway builds ignore that query flag, ignore boolean
beta header/body signals, and still preserve named Anthropic beta headers
and Bedrock anthropic_beta body fields.
Model is not deployed, but choices are shown. Reply with the number of the route you want. You can review or delete saved mappings in portal Models under Model name mappings.
Anything not working as expected? Open a ticket. Include the X-NI-Request-ID if one was returned.