Claude Code

Claude Code speaks the Anthropic Messages protocol, and Valkyrie serves your deployed model over that same protocol. You point Claude Code at your deployment with a few environment variables: the base URL, an auth token, the model name, and a context limit. Claude Code then talks to your model instead of Anthropic’s. The base URL is your API host plus the deployment slug (deployment-{id}) or an alias. Claude Code appends /v1/messages itself, so the base URL must not end in /v1.

Set it up

Open a terminal

Open a new terminal window. Everything below runs in this one shell session, so keep it open while you use Claude Code. (To make it permanent, see Persist the configuration at the end.)

Clear any existing Anthropic API key

If ANTHROPIC_API_KEY is set, it takes precedence and Claude Code will try to reach Anthropic instead of Valkyrie. Unset it:

unset ANTHROPIC_API_KEY

Set the base URL (no /v1, no quotes inside the value)

Use your deployment slug or an alias. Do not include /v1 — Claude Code adds /v1/messages on its own.

# By alias (recommended - a stable name that survives redeploys):
export ANTHROPIC_BASE_URL="https://valkyrie-back.azumo.com/acme/qwen-coder"

# ...or by raw deployment slug (deployment-{id}):
# export ANTHROPIC_BASE_URL="https://valkyrie-back.azumo.com/deployment-227"

acme/qwen-coder is only an example: acme is your account handle and qwen-coder is an alias you created. Don’t know yours, or haven’t made one? See Aliases — it shows where to create and find them in the dashboard (with a screenshot of the Alias Management screen). Prefer an alias over a raw deployment-{id}: a deployment id points at a single instance and stops working the moment that deployment is replaced, while an alias stays stable and can be re-pointed. If you haven’t set one up yet, use your deployment’s slug from Dashboard → Models instead.

Which URL do I use? Claude Code uses the Anthropic base: your slug or alias with no /v1 on the end, because Claude Code appends /v1/messages itself. The /v1 form of the same deployment is the OpenAI-compatible base, for a different set of clients:

Client	Base URL to use
Claude Code (Anthropic protocol)	`https://valkyrie-back.azumo.com/acme/qwen-coder`
Qwen Code, OpenAI SDK, LiteLLM (OpenAI protocol)	`https://valkyrie-back.azumo.com/acme/qwen-coder/v1`

Same alias (or deployment), two base URLs. Give Claude Code the /v1 form and the path doubles to /v1/v1/messages, which fails.

Paste the URL without surrounding quote characters. The "..." in the command above are shell quotes and must wrap the value, not be part of it. A value like "https://.../deployment-227" (quotes baked into the string) produces the error ... cannot be parsed as a URL. See Troubleshooting.

Set the auth token

Use a deployment key (vk_dep_...) from your dashboard. ANTHROPIC_AUTH_TOKEN sends it as Authorization: Bearer and avoids Claude Code’s one-time custom-key approval prompt. Do not set both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY.

export ANTHROPIC_AUTH_TOKEN="vk_dep_your_deployment_key"

Find your model name

Claude Code sends a model field on every request. Ask your deployment which model id it serves:

curl -s "$ANTHROPIC_BASE_URL/v1/models" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"

The response lists your model, for example:

{ "object": "list", "data": [ { "id": "qwen3.8-27b", "max_model_len": 131072 } ] }

Note the id (the model name) and max_model_len (the context window) — you need both in the next step.

Set the model and context limit

Set ANTHROPIC_MODEL to the id from the previous step. Set CLAUDE_CODE_MAX_CONTEXT_TOKENS to your model’s max_model_len.

export ANTHROPIC_MODEL="qwen3.8-27b"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="131072"

CLAUDE_CODE_MAX_CONTEXT_TOKENS is important. Without it, Claude Code assumes a Claude-sized context window (200k) and will overflow a smaller open model, producing truncation or request errors. Set it to your deployment’s real context length.

Launch Claude Code

claude --model "$ANTHROPIC_MODEL"

Verify the connection

Inside Claude Code, run:

/status

Confirm all of the following:

Anthropic base URL is your Valkyrie URL (ends in the slug/alias, not /v1).
The active credential source is ANTHROPIC_AUTH_TOKEN.
The model is your model id.

Then send a short prompt to confirm you get a real reply.

Show your model name (instead of “Opus”)

Claude Code’s status line knows the Claude model names (Opus, Sonnet, Haiku). When ANTHROPIC_MODEL is a name it doesn’t recognize, it falls back to displaying Opus even though every request still goes to your Valkyrie model. It’s cosmetic, not a misconfiguration, but you can make the UI show the real name by registering your model as a custom option:

export ANTHROPIC_CUSTOM_MODEL_OPTION="qwen3.8-27b"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Valkyrie Qwen3.8"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Self-hosted on Valkyrie"

Restart Claude Code, pick your model once with /model, and the status line then shows the name you set.

When Claude Code points at a Valkyrie base URL, all of its traffic goes to your one deployed model, including background work like conversation titles and summaries. There is no separate small/fast model quietly reaching Anthropic. Size the deployment for that full load.

Revert to normal Claude

The variables above only affect the shell session (or profile) where you set them. To go back to Anthropic’s Claude:

Unset the Valkyrie variables

In the same terminal:

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset CLAUDE_CODE_MAX_CONTEXT_TOKENS

(Opening a brand-new terminal window also works if you never persisted them.)

Remove any persisted values

If you added these to your shell profile (~/.zshrc, ~/.bashrc) or to ~/.claude/settings.json, delete those lines/keys too, otherwise they come back in every new session.

Sign back in and restart

Restart Claude Code and, if needed, sign in again:

/login

Run /status to confirm the base URL is back to Anthropic’s default and your claude.ai login (or ANTHROPIC_API_KEY) is the active credential.

Persist the configuration

To avoid re-exporting every session, keep the non-secret values in ~/.claude/settings.json and leave the token in your environment (settings.json does not expand $VARIABLES, so never put a raw key there if you can avoid committing it):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://valkyrie-back.azumo.com/acme/qwen-coder",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "131072"
  },
  "model": "qwen3.8-27b"
}

Keep export ANTHROPIC_AUTH_TOKEN="vk_dep_..." in your shell profile (or a sourced secrets file), and keep ANTHROPIC_API_KEY unset.

Troubleshooting

"... cannot be parsed as a URL"

Your ANTHROPIC_BASE_URL contains literal quote characters, e.g. the value is "https://.../deployment-227" including the ". A URL cannot contain a ", so the request fails before it’s sent. Re-export the value with the quotes wrapping it, not inside it:

export ANTHROPIC_BASE_URL="https://valkyrie-back.azumo.com/deployment-227"

Requests hit /v1/v1/messages (404 / not found)

Your base URL ends in /v1. Claude Code appends /v1/messages itself, so the base URL must stop at the slug or alias. Use .../deployment-227, not .../deployment-227/v1. The /v1 form is the OpenAI-compatible base URL, used by Qwen Code, the OpenAI SDK, and LiteLLM, not by Claude Code.

It's still talking to Anthropic, not Valkyrie

ANTHROPIC_API_KEY is still set and takes precedence. Run unset ANTHROPIC_API_KEY, then restart Claude Code. Confirm with /status that the base URL is your Valkyrie URL and the credential source is ANTHROPIC_AUTH_TOKEN.

Context overflow or truncation errors

CLAUDE_CODE_MAX_CONTEXT_TOKENS is unset or larger than your model supports. Set it to your deployment’s max_model_len (from the /v1/models call above).

503 errors, or the connection drops in and out

A 503 means the deployment isn’t reachable at that moment. It is almost never Claude Code’s fault — check the deployment:

Is it actually running? Open Dashboard → Models and confirm the deployment you pointed at is serving. A stopped, paused, or terminated deployment returns 503/404 for every request. This is the most common cause of a base URL that “used to work.”
Cold start / restart window. A deployment runs on a GPU instance that has to boot; while it’s coming up (or restarting after a crash) requests briefly 503. Wait for Dashboard → Models to show it healthy, then retry.
Empty wallet. If your balance reaches zero, the deployment is paused for billing and returns 503 until you add credit (Dashboard → Wallet) and it resumes.

If instead the first request just hangs on a slow cold start, raise Claude Code’s request timeout (default is 10 minutes):

export API_TIMEOUT_MS="900000"   # 15 minutes

The status line shows "Opus" while I use Valkyrie

Cosmetic. Claude Code falls back to the “Opus” label for model names it doesn’t recognize; requests still go to your Valkyrie model (confirm the base URL and model id with /status). To display the real name, set the ANTHROPIC_CUSTOM_MODEL_OPTION* variables in Show your model name.

A self-hosted open model is not Claude. Behavior, tool-use quality, and context limits depend entirely on the model you deployed. Size the deployment for the workload you expect from a coding agent.

Looking to let Claude Code operate Valkyrie (deploy models, read logs, manage jobs) rather than use one as its model? That’s the MCP server, see Set up the MCP server. The two integrations are independent and can be used together.

Get Started

Guides

Connect a Model

Dashboard

Security

Set it up

Show your model name (instead of “Opus”)

Revert to normal Claude

Persist the configuration

Troubleshooting

Get Started

Guides

Connect a Model

Dashboard

Security

​Set it up

​Show your model name (instead of “Opus”)

​Revert to normal Claude

​Persist the configuration

​Troubleshooting

Set it up

Show your model name (instead of “Opus”)

Revert to normal Claude

Persist the configuration

Troubleshooting