Skip to main content

Claude Code CLI

Claude Code uses the Anthropic Messages API shape. For router traffic, use the router Anthropic-compatible base URL and a router-issued bearer token.

These docs are built into the hosted GenAI Smart Router server delivered for your deployment. Examples that show the router base URL use this browser origin, so on this deployment they render as https://<router-host> and https://<router-host>/v1.

For Claude Code deployment access, contact contact@metrum.ai.

Required Environment​

Use ANTHROPIC_BASE_URL=https://<router-host>/anthropic and ANTHROPIC_AUTH_TOKEN for router traffic. Keep ANTHROPIC_API_KEY reserved for direct Anthropic traffic; setting both for the router path can cause client warnings or incorrect authentication behavior.

Router tokens can only request model groups returned by /v1/models for that same token. Set the main Claude Code model and the default subagent model to allowed router model groups; otherwise Claude Code may send some Anthropic Messages requests with a model value the router key cannot use.

Record the Claude Code version used for deployment validation with claude --version; CLI flags can change over time.

unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://<router-host>/anthropic"
export ANTHROPIC_AUTH_TOKEN="rtr_metrum_<user>_<project>_<env>_<key>_<secret>"
export ANTHROPIC_MODEL="<allowed-model-group>"
export CLAUDE_CODE_SUBAGENT_MODEL="<allowed-model-group>"

Check the allowed groups with the same router token before choosing values:

curl "https://<router-host>/v1/models" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

One-Shot Check​

Use one of the model group IDs returned by /v1/models for --model or ANTHROPIC_MODEL. See Available Models And Access if you need to check which groups your token can request.

claude --bare --print --model "<allowed-model-group>" \
  "Reply with exactly: router claude ok"

Interactive Usage​

claude --model "<allowed-model-group>"

Use the same deployment-defined coding group for mixed coding and image tasks only after the deployment has validated an image-capable Anthropic Messages target in that group. Some hosted examples use big-coder as a coding-oriented group name; your deployment may use a different group name. A group's aggregate image modality can come from an OpenAI Chat or Responses target and does not prove that Claude Code image traffic is eligible. When a Messages image target exists, the router filters image-bearing requests to that pool while text-only and ordinary tool requests continue to use the normal coding targets.

Subagent Model Routing​

Claude Code can resolve subagent models separately from the main session. For router keys that are limited to one or more model groups, pin both the main session and subagents to groups returned by /v1/models.

For local project settings, use placeholders in shared examples and keep real router tokens out of version control:

.claude/settings.local.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<router-host>/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "rtr_metrum_<user>_<project>_<env>_<key>_<secret>",
    "ANTHROPIC_MODEL": "<allowed-model-group>",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<allowed-model-group>"
  }
}

If an individual subagent should use a different router group, first leave CLAUDE_CODE_SUBAGENT_MODEL unset or set it to inherit behavior for that run. Then set the different group in the subagent frontmatter and make sure the same router token can see it in /v1/models:

.claude/agents/router-subagent.md
---
name: router-subagent
description: Work on the assigned task using the selected router model group.
model: <allowed-model-group>
---

Complete the assigned task and report the result.

If Claude Code still sends 403 model-not-allowed, check the main model, CLAUDE_CODE_SUBAGENT_MODEL, and any subagent frontmatter model values against /v1/models using the same ANTHROPIC_AUTH_TOKEN. A pinned CLAUDE_CODE_SUBAGENT_MODEL takes precedence over per-subagent frontmatter, so unset or inherit it before testing a different frontmatter model group.

Tool Smoke​

Run tool smokes inside a disposable container or equivalent isolated workspace because the command intentionally grants file and shell tools. Pass only the router base URL and a scoped router token into the sandbox, and mount only the scratch directory where the smoke file should be written.

mkdir -p "$PWD/claude-tool-smoke"
docker run --rm --network host --cap-drop ALL --security-opt no-new-privileges \
  --cpus 1 --memory 1g --pids-limit 256 --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=256m \
  --mount type=bind,source="$PWD/claude-tool-smoke",target=/workspace \
  -e "ANTHROPIC_BASE_URL={{origin}}/anthropic" \
  -e "ANTHROPIC_AUTH_TOKEN=$ANTHROPIC_AUTH_TOKEN" \
  -w /workspace "$TOOL_SMOKE_IMAGE" \
  claude --bare --print --model "<allowed-model-group>" \
    --permission-mode bypassPermissions \
    --allowedTools "Write,Bash" \
    "Create claude_tool_smoke.txt containing exactly claude-tool-ok, run cat claude_tool_smoke.txt, then finish with claude-tool-ok."

The requested model must be allowed by the caller token. Deployment admins decide which model groups each key may use.

Image Input​

Claude Code sends image work through the Anthropic Messages API shape when an image is attached in the conversation. Use a deployment-defined router model group that is allowed for the caller token and has validation evidence for image input on the Anthropic Messages surface. The router filters image-bearing Messages requests to targets that advertise image in input_modalities and are eligible for the inbound anthropic dialect and caller output cap.

/v1/models confirms that the token may request the group, but group-level image metadata can be backed by a different API skin. Before rollout, run the Messages image smoke below. A 502 no-eligible-target response means the group is authorized but has no target validated for that exact Messages image shape; ask the deployment administrator to add or enable a validated Anthropic Messages image target rather than retrying the same request.

For non-interactive validation, use the same Anthropic-compatible payload shape Claude Code sends:

curl "https://<router-host>/anthropic/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "<allowed-model-group>",
  "max_tokens": 64,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "image", "source": {"type": "url", "url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}}
    ]
  }]
}'

The legacy /v1/messages and /v1/messages/count_tokens paths remain compatible for existing clients. New Claude Code and Anthropic-compatible client setup should use /anthropic as the base URL, which sends requests to /anthropic/v1/messages and keeps Anthropic-compatible traffic visually separate from OpenAI-compatible /v1 traffic.

Image-bearing Claude Code requests bypass router response caching. Usage records include image count and upstream cost fields when the upstream reports them.

For the full VLM routing configuration and equivalent OpenAI API examples, see Image Analysis And VLM Routing.

For the broader coding-agent validation matrix, including opencode, aider, and IDE/agent clients, see Coding-Agent Client Matrix.