Claude Code - Hivenet Router

Claude Code can use Hivenet Router as an Anthropic-format inference gateway. Claude Code sends requests to the router’s:

POST /v1/messages

endpoint. Hivenet Router authenticates the client, checks model access and quotas, selects an eligible llm agent, and forwards the original request to the backend at the same path.

Hivenet Router does not translate OpenAI Chat Completions into the Anthropic Messages format.The inference backend must serve /v1/messages itself. The model and backend must also support the tool-calling behavior Claude Code needs.Anthropic documents how Claude Code connects to gateways, but does not provide support for running Claude Code against non-Claude models through them.

Prerequisites

Before configuring Claude Code, you need:

a reachable Hivenet Router router
a Hivenet Router client API key
at least one healthy agent registered with the llm capability
a backend that implements the Anthropic Messages API
a model with reliable structured tool calling
HTTPS when the router is reached over an untrusted network

The backend should support:

POST /v1/messages
POST /v1/messages/count_tokens

Token counting is optional in the Claude Code gateway protocol, but implementing it gives Claude Code exact context measurements and avoids relying on local estimates.

Prepare a compatible backend

vLLM supports the Anthropic Messages API and can serve tool-capable open models to Claude Code. A typical command resembles:

vllm serve <model-source> \
  --host 0.0.0.0 \
  --port 8888 \
  --served-model-name hivenet-router-code-model \
  --enable-auto-tool-choice \
  --tool-call-parser <model-specific-parser>

Replace:

<model-source>

with the model you are loading, and:

<model-specific-parser>

with the tool-call parser required by that model. Tool-call configuration differs by model family. Check that the selected parser is supported by the exact model and vLLM version you deploy.

Use a stable served-model alias

Prefer a short, stable alias for the model Claude Code will request:

hivenet-router-code-model

Current vLLM guidance recommends avoiding slash-containing Hugging Face IDs in this integration path. The alias also separates the client-facing model name from the underlying model repository:

vllm serve Qwen/<model-repository> \
  --served-model-name hivenet-router-code-model \
  ...

Make the Hivenet Router agent register the same value:

./bin/hivenet-agent \
  --engine vllm \
  --backend-url http://localhost:8888 \
  --model hivenet-router-code-model \
  --router-grpc <router-host>:50051 \
  --jwt-secret-file /etc/hivenet-router/jwt.secret

The value must match across:

vLLM’s --served-model-name
the Hivenet Router agent’s registered model
the Claude Code model mapping
the API key’s model restrictions or per-model quotas

Test the backend directly

Before adding Hivenet Router or Claude Code to the path, confirm that the backend accepts an Anthropic-format request:

curl -X POST \
  http://localhost:8888/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hivenet-router-code-model",
    "max_tokens": 32,
    "messages": [
      {
        "role": "user",
        "content": "Reply with one short sentence."
      }
    ]
  }'

The response should use the Anthropic Messages format rather than the OpenAI Chat Completions format. Test token counting as well:

curl -X POST \
  http://localhost:8888/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hivenet-router-code-model",
    "messages": [
      {
        "role": "user",
        "content": "Count the tokens in this request."
      }
    ]
  }'

A successful response resembles:

{
  "input_tokens": 10
}

The exact count depends on the tokenizer.

Test the Hivenet Router path

List the models visible to the Claude Code API key:

curl \
  -H "Authorization: Bearer <hivenet-router-api-key>" \
  https://router.example.com/v1/models \
  | jq -r '.data[].id'

Confirm that the list contains:

hivenet-router-code-model

Then test the Messages endpoint through Hivenet Router:

curl -X POST \
  https://router.example.com/v1/messages \
  -H "Authorization: Bearer <hivenet-router-api-key>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hivenet-router-code-model",
    "max_tokens": 32,
    "messages": [
      {
        "role": "user",
        "content": "Reply with one short sentence."
      }
    ]
  }'

This verifies:

client authentication
model access
routing
agent connectivity
backend Messages support
response forwarding

max_tokens is required by the Anthropic Messages request format.A hand-written request without it may be rejected by the backend even though the equivalent Chat Completions request succeeds.

Install Claude Code

macOS, Linux, or WSL
Windows PowerShell

curl -fsSL https://claude.ai/install.sh \
  | bash

irm https://claude.ai/install.ps1 \
  | iex

Verify the installation:

claude --version

Use current Claude Code and inference-backend releases. Pin a client or backend version only after reproducing a specific compatibility regression in your deployment. Treat old version pins from earlier setup notes as historical workarounds rather than permanent requirements.

Configure Claude Code

Set the router URL, client credential, and model aliases before launching Claude Code:

unset ANTHROPIC_API_KEY

export ANTHROPIC_BASE_URL="https://router.example.com"
export ANTHROPIC_AUTH_TOKEN="<hivenet-router-api-key>"

export ANTHROPIC_DEFAULT_OPUS_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_SONNET_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="hivenet-router-code-model"

claude --model sonnet

Do not add /v1 to the base URL. Correct:

https://router.example.com

Incorrect:

https://router.example.com/v1

Claude Code appends:

/v1/messages

itself. Including /v1 in the configured base URL can produce:

/v1/v1/messages

Use the bearer-token variable

Use:

ANTHROPIC_AUTH_TOKEN

for a Hivenet Router client key. Claude Code sends it as:

Authorization: Bearer <hivenet-router-api-key>

This is the authentication header Hivenet Router accepts. Do not use only:

ANTHROPIC_API_KEY

Claude Code sends that value as:

x-api-key: <value>

Hivenet Router client authentication does not read x-api-key. Unsetting ANTHROPIC_API_KEY also prevents an unrelated Anthropic API key from taking part in credential selection:

unset ANTHROPIC_API_KEY

You do not normally need to sign out of an existing claude.ai account.ANTHROPIC_AUTH_TOKEN takes precedence while it is set. The saved login remains available and becomes active again after you remove the gateway variables.Run /logout only when you deliberately want to remove the saved login or Claude Code reports an unresolved authentication conflict.

Map the model aliases

Claude Code uses built-in model aliases for different kinds of work.

Alias	Environment variable	Typical use
`opus`	`ANTHROPIC_DEFAULT_OPUS_MODEL`	Complex reasoning and planning
`sonnet`	`ANTHROPIC_DEFAULT_SONNET_MODEL`	Main coding work
`haiku`	`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Faster and background tasks

You may map every alias to one model:

export ANTHROPIC_DEFAULT_OPUS_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_SONNET_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="hivenet-router-code-model"

Or map them to different Hivenet Router models:

export ANTHROPIC_DEFAULT_OPUS_MODEL="code-model-large"
export ANTHROPIC_DEFAULT_SONNET_MODEL="code-model-standard"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="code-model-fast"

Every mapped model must:

appear in /v1/models for the client key
be registered by a healthy llm agent
support the request features Claude Code sends
be included in the key’s model restrictions or per-model quotas

Map haiku even when you intend to work mainly through sonnet or opus. Claude Code can use the Haiku alias for background functionality.

Verify the active configuration

Start Claude Code:

claude --model sonnet

Then run:

/status

Confirm that the status view shows:

the Hivenet Router address as the Anthropic base URL
ANTHROPIC_AUTH_TOKEN as the active credential source
the intended model or model alias

If the Hivenet Router URL is missing, the environment variables did not reach that Claude Code process. This commonly happens when:

Claude Code was started from another terminal
an editor was launched before the variables were exported
a settings file overrides the shell value
a wrapper or background process uses another environment

Test the coding workflow

Start with a simple prompt:

Read the current directory and tell me what kind of project this is.

Then test a harmless tool action:

Create a file named hivenet-router-test.txt containing the word connected.

Confirm that Claude Code:

proposes or invokes the appropriate file tool
receives a structured tool response from the model
creates the expected file
continues the conversation after the tool result

A model that produces good text but cannot emit the expected structured tool calls is not sufficient for Claude Code. Remove the test file afterward:

rm hivenet-router-test.txt

Make the configuration persistent

Claude Code supports several settings scopes.

File	Scope	Suitable for credentials?
`~/.claude/settings.json`	All projects for one user	Yes, but stored as plaintext
`.claude/settings.local.json`	One project for one user	Yes, when ignored by Git
`.claude/settings.json`	Shared project configuration	No

A user-wide configuration can look like:

{
  "model": "sonnet",
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.example.com",
    "ANTHROPIC_AUTH_TOKEN": "<hivenet-router-api-key>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "hivenet-router-code-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "hivenet-router-code-model",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "hivenet-router-code-model"
  }
}

Do not put a Hivenet Router API key in the shared:

.claude/settings.json

file.That file is intended for source control. Use a user setting, .claude/settings.local.json, shell environment, or credential helper instead.

Settings-file environment values take precedence over matching values exported by the shell. Use /status to confirm which value is active.

Use a credential helper

For short-lived or externally managed keys, configure:

{
  "apiKeyHelper": "~/bin/get-hivenet-router-key.sh",
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.example.com",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "hivenet-router-code-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "hivenet-router-code-model",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "hivenet-router-code-model"
  }
}

The helper must print the current raw Hivenet Router key to standard output. Claude Code sends a helper-generated credential in both:

Authorization: Bearer <value>
x-api-key: <value>

Hivenet Router uses the Authorization header. By default, Claude Code caches the helper result for five minutes and runs it again after an HTTP 401. Change the cache period with:

export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000

The value is in milliseconds.

ANTHROPIC_AUTH_TOKEN has higher credential precedence than apiKeyHelper.Remove the static token when the helper should become authoritative.

Add a custom model to the picker

The alias mappings are the simplest way to expose Hivenet Router models. You can also add one explicit custom entry:

export ANTHROPIC_CUSTOM_MODEL_OPTION="hivenet-router-code-model"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Hivenet Router code model"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Served through Hivenet Router"

Restart Claude Code, then open:

/model

The custom entry appears alongside the built-in aliases.

Gateway model discovery

Claude Code can optionally query:

GET /v1/models?limit=1000

at startup:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

However, current Claude Code discovery ignores returned IDs that do not begin with:

claude
anthropic

Typical open-model IDs therefore do not appear automatically. Use alias mappings or ANTHROPIC_CUSTOM_MODEL_OPTION instead of renaming an open model to imply that it is a Claude model.

Do not combine gateway model discovery with:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

The nonessential-traffic setting disables discovery.

Restricted-egress environments

Claude Code can make non-inference requests outside the configured gateway path for update checks, telemetry, release information, and other auxiliary behavior. On a network that permits access only to Hivenet Router, set:

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

This is optional and should not be part of the default configuration. It also:

disables automatic updates
disables gateway model discovery
suppresses the fast-mode availability check
leaves some WebFetch safety traffic subject to separate settings

Plan another update process before enabling it permanently.

Request and header behavior

Claude Code sends Anthropic-format requests, including evolving:

anthropic-version headers
anthropic-beta headers
tool schemas
system content
context-management fields
reasoning and output-configuration fields

Hivenet Router forwards the original request body and headers through the selected agent to the backend. The backend must understand the fields that arrive.

Do not place an intermediary between Hivenet Router and the backend that removes unfamiliar anthropic-* headers or request fields.Claude Code adds capabilities over time. A fixed allowlist of observed headers can break a later Claude Code release.

Streaming

Claude Code expects server-sent events to arrive progressively. The complete path must preserve streaming:

Claude Code
  → reverse proxy
  → Hivenet Router router
  → Hivenet Router agent
  → inference backend

When output appears only after the model finishes, check:

whether the backend returns text/event-stream
whether the agent is current
whether the reverse proxy buffers responses
whether proxy timeouts are long enough
whether the client requested streaming

For Nginx, the inference route commonly needs buffering disabled:

proxy_buffering off;
proxy_cache off;

The exact reverse-proxy configuration depends on your deployment.

Compatibility with new Claude Code features

Claude Code may send fields that an older or non-Anthropic backend does not support. Common failures include backend errors naming:

thinking
adaptive
context_management
output_config
strict
defer_loading

The preferred fix is to update the backend and use a model integration that supports the request. For diagnosis, you can temporarily disable adaptive thinking:

export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

You can also disable experimental beta capabilities:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

These variables remove capabilities from the client request. They do not make an incompatible model support tools or other missing behavior. Use them as targeted compatibility controls rather than permanent defaults.

Claude Code can automatically recover from some upstream capability rejections only when it receives the original error wording.Hivenet Router currently preserves structured Hivenet Router errors but can wrap an unstructured backend error. When a new client field causes a backend 400, inspect the backend log directly rather than relying only on the final router response.

Use Hivenet Router and Anthropic side by side

A saved claude.ai login can remain on the machine. Create a launcher for Hivenet Router:

#!/usr/bin/env bash

unset ANTHROPIC_API_KEY

export ANTHROPIC_BASE_URL="https://router.example.com"
export ANTHROPIC_AUTH_TOKEN="<hivenet-router-api-key>"

export ANTHROPIC_DEFAULT_OPUS_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_SONNET_MODEL="hivenet-router-code-model"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="hivenet-router-code-model"

exec claude --model sonnet "$@"

Save it as:

~/bin/claude-hivenet-router

and make it executable:

chmod +x \
  ~/bin/claude-hivenet-router

For a normal Anthropic session, start Claude Code without the Hivenet Router variables:

env \
  -u ANTHROPIC_BASE_URL \
  -u ANTHROPIC_AUTH_TOKEN \
  -u ANTHROPIC_DEFAULT_OPUS_MODEL \
  -u ANTHROPIC_DEFAULT_SONNET_MODEL \
  -u ANTHROPIC_DEFAULT_HAIKU_MODEL \
  claude

The saved claude.ai login becomes active again.

Observe Claude Code traffic

Audit records identify the tenant, model, selected agent, status, and request duration. Search one tenant in Loki:

{
  job="hivenet-router",
  log_type="audit",
  tenant_id="claude-code"
}
  | json

Inspect requests by model:

{
  job="hivenet-router",
  log_type="audit",
  model="hivenet-router-code-model"
}
  | json

Request rate:

sum by (tenant_id, model) (
  rate(
    hivenet_router_routing_requests_routed_total[5m]
  )
)

Give Claude Code its own client key when you need its traffic separated from other applications.

Troubleshooting

The gateway credential did not reach the process. Check:

echo "$ANTHROPIC_BASE_URL"
echo "${ANTHROPIC_AUTH_TOKEN:+set}"

Then start Claude Code from the same shell. Run /status after it opens.

`/status` shows no Anthropic base URL

Claude Code is not using the Hivenet Router endpoint. Check for:

a missing environment variable
a settings-file override
an editor or launcher with another environment
a misspelled variable name

Requests return `401`

Use:

ANTHROPIC_AUTH_TOKEN

rather than only:

ANTHROPIC_API_KEY

Confirm that the raw Hivenet Router client key is being sent, not its SHA-256 hash. Test it directly:

curl \
  -H "Authorization: Bearer <hivenet-router-api-key>" \
  https://router.example.com/v1/models

Requests return a plain `404`

Check the base URL. It should not end in:

/v1

Also confirm that the request reaches:

/v1/messages

rather than an unsupported path.

The router returns `model_not_found`

Compare the configured alias with:

curl \
  -H "Authorization: Bearer <hivenet-router-api-key>" \
  https://router.example.com/v1/models \
  | jq -r '.data[].id'

Check:

capitalization
punctuation
served-model alias
agent --model
API-key model access
agent health

The backend returns `404` for `/v1/messages`

The backend does not implement the Anthropic Messages endpoint. A backend that supports only:

/v1/chat/completions

cannot serve Claude Code through the current Hivenet Router passthrough. Use an Anthropic-compatible backend or another coding client that speaks OpenAI Chat Completions.

Text works but tools fail

Check that:

the model supports structured tool calls
vLLM uses --enable-auto-tool-choice
the selected --tool-call-parser matches the model
the backend returns Anthropic-format tool-use blocks
the model follows tool schemas reliably

Test the backend directly to isolate it from Hivenet Router.

The backend rejects `system` messages

Upgrade the backend and test the current Claude Code request against it directly. Do not begin by pinning an old Claude Code release. First confirm whether the backend’s current Anthropic Messages implementation accepts the system-content shape the client sends.

The backend rejects `thinking` or `adaptive`

Update the backend first. As a compatibility test:

export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

Restart Claude Code after changing the variable.

The backend rejects beta fields

As a temporary diagnostic:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

This may disable context management and newer tool features.

Claude Code retries and Hivenet Router later reports no eligible agent

Inspect the backend’s first error. A backend rejection that Hivenet Router treats as retryable can cause the request session to try other agents and exclude agents that already failed. Check:

Router
Agent
vLLM

docker compose logs router \
  | grep -iE "messages|policy|failed|exhaust"

docker compose logs <agent-service> \
  | tail -100

docker compose logs <vllm-service> \
  | tail -100

The most useful validation message often appears in the backend log.

Streaming arrives only after completion

Check:

backend SSE behavior
Hivenet Router agent version
reverse-proxy buffering
proxy read and idle timeouts
response Content-Type

Test the backend and router separately with streaming curl requests.

Token counting fails

Test the backend directly:

curl -i -X POST \
  http://localhost:8888/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hivenet-router-code-model",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

Claude Code can estimate context locally when token counting is unavailable, but backend support gives more accurate results.

The model picker does not show Hivenet Router models

Use the mapped aliases:

/model sonnet
/model opus
/model haiku

Or configure:

ANTHROPIC_CUSTOM_MODEL_OPTION

Gateway discovery ignores typical open-model IDs that do not begin with claude or anthropic.

Next steps

OpenCode

Connect a coding agent through OpenAI Chat Completions.

Use from code

Call Hivenet Router from SDKs, scripts, and custom applications.

Chat completions and messages

Review the Anthropic and OpenAI inference paths.

API keys

Configure model access, quotas, expiration, and credential rotation.

vLLM agent

Deploy and register the backend serving Claude Code requests.

Audit logging

Investigate Claude Code requests by tenant, model, status, and agent.

​Prerequisites

​Prepare a compatible backend

​Use a stable served-model alias

​Test the backend directly

​Test the Hivenet Router path

​Install Claude Code

​Configure Claude Code

​Use the bearer-token variable

​Map the model aliases

​Verify the active configuration

​Test the coding workflow

​Make the configuration persistent

​Use a credential helper

​Add a custom model to the picker

​Gateway model discovery

​Restricted-egress environments

​Request and header behavior

​Streaming

​Compatibility with new Claude Code features

​Use Hivenet Router and Anthropic side by side

​Observe Claude Code traffic

​Troubleshooting

​Claude Code opens the login screen

​/status shows no Anthropic base URL

​Requests return 401

​Requests return a plain 404

​The router returns model_not_found

​The backend returns 404 for /v1/messages

​Text works but tools fail

​The backend rejects system messages

​The backend rejects thinking or adaptive

​The backend rejects beta fields

​Claude Code retries and Hivenet Router later reports no eligible agent

​Streaming arrives only after completion

​Token counting fails

​The model picker does not show Hivenet Router models

​Next steps

OpenCode

Use from code

Chat completions and messages

API keys

vLLM agent

Audit logging

Prerequisites

Prepare a compatible backend

Use a stable served-model alias

Test the backend directly

Test the Hivenet Router path

Install Claude Code

Configure Claude Code

Use the bearer-token variable

Map the model aliases

Verify the active configuration

Test the coding workflow

Make the configuration persistent

Use a credential helper

Add a custom model to the picker

Gateway model discovery

Restricted-egress environments

Request and header behavior

Streaming

Compatibility with new Claude Code features

Use Hivenet Router and Anthropic side by side

Observe Claude Code traffic

Troubleshooting

Claude Code opens the login screen

`/status` shows no Anthropic base URL

Requests return `401`

Requests return a plain `404`

The router returns `model_not_found`

The backend returns `404` for `/v1/messages`

Text works but tools fail

The backend rejects `system` messages

The backend rejects `thinking` or `adaptive`

The backend rejects beta fields

Claude Code retries and Hivenet Router later reports no eligible agent

Streaming arrives only after completion

Token counting fails

The model picker does not show Hivenet Router models

Next steps