Best practicesClaude Code

Claude Code

Route Claude Code traffic through Velrix with Anthropic-compatible gateway settings. Keep bearer credentials scoped, put non-secret defaults in Claude settings, and confirm every session in request logs.

Use a dedicated Velrix key for Claude Code sessions.

Prefer a single gateway base URL over per-project provider URLs.

Keep secret values in the shell, CI secret store, or OS keychain.

Secrets

Environment variables

Claude Code supports a custom Anthropic base URL and a custom Authorization bearer token. Set these before launching claude.

Shell

export VELRIX_API_KEY="vk_live_..."
export ANTHROPIC_BASE_URL="https://api.velrix.ai"
export ANTHROPIC_AUTH_TOKEN="$VELRIX_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
export CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1

claude

Use bearer-token mode for Velrix

ANTHROPIC_AUTH_TOKEN is sent as an Authorization bearer token by Claude Code. Use it for Velrix keys. Avoid placing live keys in checked-in .claude/settings.json files.

Configuration

Settings file

Use settings.json for non-secret defaults that should apply to every Claude Code session.

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.velrix.ai",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING": "1"
  },
  "model": "claude-sonnet-4-6"
}

User settings

Apply to all local projects.

~/.claude/settings.json

Shared project settings

Commit only non-secret team defaults.

.claude/settings.json

Local project settings

Personal overrides that should stay uncommitted.

.claude/settings.local.json

Routing

Model routing

Choose automatic routing for broad coding tasks, then pin models for workflows that need reproducibility.

Model selection

# Let Velrix policy choose the route.
export ANTHROPIC_MODEL="claude-sonnet-4-6"

# Or pin a catalog model when the workflow needs repeatability.
export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.5"

# Add an explicit picker entry if the model is not listed by Claude Code.
export ANTHROPIC_CUSTOM_MODEL_OPTION="anthropic/claude-sonnet-4.5"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Claude Sonnet via Velrix"

Automatic routing

Good for exploratory coding work where Velrix can select by health, cost, latency, and policy.

Pinned model

Good for review, test generation, or migration tasks where consistent behavior matters more than route flexibility.

Gateway model discovery

Enable discovery when you want Claude Code to populate the model picker from Velrix's gateway model endpoint. Use explicit custom entries when discovery is unavailable or too broad for a team rollout.

Research

References

These external references informed the Claude Code configuration fields shown above.

Claude Code environment variables

Official reference for ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, gateway discovery, and related controls.

Claude Code model configuration

Official guidance for custom model picker entries, alias overrides, and pinning models for third-party deployments.

Claude Code settings

Official scope and settings.json behavior for user and project-level Claude Code configuration.

Operations

Verify traffic

Confirm the first Claude Code request appears under the expected API key, model, provider, and workspace.

View request logs Review API keys