Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

Claude Code launch configuration

Configure Claude Code credentials, gateway routing, and model selection for certification

Last updated on:

Claude Code and the Anthropic SDKs reach nexus through the native Messages edge mounted under /anthropic. Clients change only the base URL and credentials; upstream Anthropic API keys are never accepted at the edge.

Environment matrix

Section titled “Environment matrix”
Variable Value Notes
ANTHROPIC_BASE_URL http://<nexus-host>:14450/anthropic Must include the /anthropic prefix. The SDK appends /v1/messages.
ANTHROPIC_AUTH_TOKEN nxs_<prefix>_<secret> Preferred for Claude Code. Sent as Authorization: Bearer.
ANTHROPIC_API_KEY nxs_<prefix>_<secret> Alternate launch mode supported by the Anthropic SDK. Sent as x-api-key. In Claude Code a custom value triggers a one-time in-client approval prompt.
ANTHROPIC_MODEL Registry model id Main model. Use a bare registry id (claude-sonnet-4-6) or a routed spec (anthropic/claude-sonnet-4-6).
ANTHROPIC_SMALL_FAST_MODEL Registry model id Claude Code’s background/utility model (e.g. claude-haiku-4-5-20251001); it must also resolve in the registry or background calls fail.

Both credential env vars carry the same nexus API key. Do not point Claude Code at an upstream Anthropic key.

Credential precedence

Section titled “Credential precedence”

Claude Code prefers a logged-in Claude subscription (OAuth) over ANTHROPIC_AUTH_TOKEN. When an account is logged in, Claude Code attaches the subscription credential instead of the gateway token, which the edge rejects with authentication_error (the edge accepts nexus keys only). To launch Claude Code against nexus, use a session that is not logged into a subscription — for example an isolated configuration directory:

Terminal window
export CLAUDE_CONFIG_DIR=/path/to/clean-claude-home   # no subscription login

Example launch

Section titled “Example launch”
Terminal window
export ANTHROPIC_BASE_URL=http://127.0.0.1:14450/anthropic
export ANTHROPIC_AUTH_TOKEN=nxs_your_prefix_your_secret
# or: export ANTHROPIC_API_KEY=nxs_your_prefix_your_secret
claude  # or your Claude Code entrypoint

Model selection

Section titled “Model selection”

Claude Code’s model picker must use ids present in the tenant-visible registry catalog (GET /v1/models on the OpenAI edge lists the same catalog). Extended-thinking sessions pin to Anthropic upstreams automatically when thinking is enabled on the request.

Observability

Section titled “Observability”

Every Messages and count_tokens call records request analytics with usage, cache token classes, cost, attempt trail, and audit events using the same pipeline as /v1/chat/completions. Verify rows in the console Requests view or via the query API using the x-nexus-request-id response header.

Certification

Section titled “Certification”

Pinned SDK versions and the automated battery live under test-suite/compat/:

  • Python: test_anthropic_native_certification.py, test_claude_code_session_battery.py
  • TypeScript: test-suite/node/tests/anthropic-native-certification.test.ts
  • SDK pins: spec/anthropic-sdk-provenance.json

Run from nexus/:

Terminal window
NEXUS_COMPAT_ENABLE_ANTHROPIC=1 just test-compat-anthropic-native

Manual checklist: claude-code/session-battery.md.