Claude Code
Configure Claude Code to use BullSequana AI through the Anthropic-compatible API.
Claude Code connects to BullSequana AI through the Anthropic Messages API endpoint on the BSQAI API. Unlike other developer tools, Claude Code uses the Anthropic wire format instead of the OpenAI-compatible path.
The backend translates requests and serves them with the models installed on the platform. No Anthropic account or subscription is required. Claude Code keeps running its own tools on your local machine — the backend only handles the model turns.
What to use
Use:
- API type: Anthropic Messages API
- base URL:
https://api.<platform-domain>/anthropic - token:
sk-bsq-...API key (sent asX-Api-Key)
1. Install Claude Code
npm install -g @anthropic-ai/claude-code
claude --versionDo not log in to Anthropic when prompted. The environment variables in step 4 replace Anthropic authentication entirely.
2. Get a BSQAI API key
Create one under API Keys in the Portal's account menu, at the bottom of the sidebar. The full secret is shown only once. It looks like sk-bsq-v1-….
Give the key chat.message.create. Every route under /anthropic requires it, including the model list in step 3. To use an Agent configuration, also give it agent.configuration.use; without it, Agents are left out of the model list and an Agent id is refused. If you belong to a group in the tenant, also choose the Team the key's usage counts for. It cannot be changed later, and that team's monthly BCU cap applies to the key. See Create and use an API key.
See OmniChat — API Keys.
3. Find available models
Query the Anthropic-compatible models endpoint to see which models are available to your account:
export ANTHROPIC_BASE_URL=https://api.<platform-domain>/anthropic
export ANTHROPIC_API_KEY=sk-bsq-v1-...
curl -s -H "x-api-key: $ANTHROPIC_API_KEY" "$ANTHROPIC_BASE_URL/v1/models" \
| jq -r '.data[] | [.id, .display_name] | @tsv'The list is scoped to your account: agent configurations you can access appear first, followed by installed chat models.
Pick two ids from the list:
- a main model for your prompts (e.g.
claude-model-gpt-5.4) - a small/fast model for background chores (e.g.
claude-model-qwen-3.5-9B)
4. Set all seven environment variables
Claude Code has internal model slots for Sonnet, Opus, and Haiku. Any slot left unset defaults to an Anthropic model id that does not exist on this platform and returns a 404. Set all seven variables.
The Portal writes this block for you, with the model id already prefixed: open the model in Studio → Available models, go to Use model, and pick Claude Code under Use with a coding agent. See Studio — Use model.
Save as source_env_vars.sh:
#!/bin/sh
export ANTHROPIC_BASE_URL=https://api.<platform-domain>/anthropic
export ANTHROPIC_API_KEY=sk-bsq-v1-...
# The model that answers you.
export ANTHROPIC_MODEL=claude-model-<main-model-from-step-3>
# Claude Code fills these on its own. Unset slots default to Anthropic ids that 404 here.
export ANTHROPIC_DEFAULT_SONNET_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_OPUS_MODEL=$ANTHROPIC_MODEL
# Background traffic (session titles, classifications). Point at something cheap.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-model-<fast-model-from-step-3>
export ANTHROPIC_SMALL_FAST_MODEL=$ANTHROPIC_DEFAULT_HAIKU_MODELAdd the model's limits
Claude Code does not know the context window of a platform model, so it cannot tell when to compact a long session. It also asks for up to 32,000 output tokens, more than a small deployment holds. Add the model's limits to the same file:
# Maximum output tokens per answer.
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=<max-output-tokens>
# Compact before the conversation reaches the model's context window.
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=<context-window>CLAUDE_CODE_AUTO_COMPACT_WINDOW accepts values from 100000. For a model with a smaller context window, set it to 100000 and add CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, the share of that window to fill before compacting: (context window − max output tokens) × 100 / 100000, rounded down. A model with a 32,768-token window and 8,192 output tokens uses 24.
CLAUDE_CODE_MAX_CONTEXT_TOKENS has no effect on claude-model-* ids. The Portal adds these variables with the model's values.
source ./source_env_vars.sh5. Check for settings file overrides
Claude Code merges environment variables from its settings files over your shell exports. If a settings file points elsewhere, your shell configuration is silently ignored:
jq '.env' ~/.claude/settings.jsonIf that prints ANTHROPIC_* keys, either remove them or move your entire configuration there instead (see Make the configuration permanent).
6. Run Claude Code
claudeVerify the platform is serving turns:
> what model are you?Inside the session, /model should list your configured ids, not Anthropic's built-in model names.
Use an Agent configuration
An Agent on the platform can be used as a model in Claude Code. It supplies the model and prepends its system prompt to every turn.
The agent configuration id is a uuid that changes if the agent is recreated. Resolve it by name at startup rather than hardcoding it:
AGENT_NAME="Simplified technical english GPT"
AGENT_ID=$(curl -sS -H "x-api-key: $ANTHROPIC_API_KEY" \
"$ANTHROPIC_BASE_URL/v1/models" \
| jq -r --arg n "$AGENT_NAME" '.data[] | select(.display_name == $n) | .id')
export ANTHROPIC_MODEL="$AGENT_ID"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$AGENT_ID"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$AGENT_ID"
# Background traffic should NOT use the agent — it has no use for the system prompt.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-model-<fast-model>
export ANTHROPIC_SMALL_FAST_MODEL=$ANTHROPIC_DEFAULT_HAIKU_MODELTo give the agent a readable name in the /model picker:
export ANTHROPIC_CUSTOM_MODEL_OPTION="$AGENT_ID"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="$AGENT_NAME"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Agent configuration on the platform"Make the configuration permanent
Shell exports die with the shell. For a permanent setup, put the configuration in the Claude Code settings file:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.<platform-domain>/anthropic",
"ANTHROPIC_API_KEY": "sk-bsq-v1-...",
"ANTHROPIC_MODEL": "claude-model-<main-model>",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-model-<main-model>",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-model-<main-model>",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-model-<fast-model>",
"ANTHROPIC_SMALL_FAST_MODEL": "claude-model-<fast-model>",
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "<max-output-tokens>",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "<context-window>"
}
}Save as ~/.claude/settings.json for global configuration or .claude/settings.json inside a repository for per-project overrides. Variable interpolation ($VAR) does not work in settings files — spell out every id. Restart claude after editing.
Call the API directly (SDK or curl)
The Anthropic-compatible endpoint also works with the official Anthropic SDK and curl, independent of Claude Code:
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.<platform-domain>/anthropic",
api_key="sk-bsq-v1-...",
)
message = client.messages.create(
model="claude-model-<model-name>",
max_tokens=4096,
messages=[{"role": "user", "content": "Hello"}],
)curl -s "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "content-type: application/json" \
-d '{"model":"claude-model-<model-name>","max_tokens":1024,
"messages":[{"role":"user","content":"Hello"}]}'Direct SDK and curl callers may also use bare model names (e.g. gpt-5.4) without the claude-model- prefix. Claude Code requires the prefix.
Model id format
Claude Code silently discards any model id that does not begin with claude or anthropic. The prefixes are required.
| Id format | Resolves to | Effect |
|---|---|---|
claude-agent-<uuid> | An agent configuration (permission-checked) | Supplies the model and prepends its system prompt |
claude-model-<name> | An installed model on the platform | No system prompt injected |
Bare <name> | Same installed model (SDK and curl only) | No system prompt injected |
| Anything else | 404 | Including all of Anthropic's own model ids |
Reasoning models
Reasoning models work through the Anthropic-compatible endpoint. Behavior depends on the model:
- Models that stream reasoning (e.g.
qwen3-235b-a22b-thinking-2507) producethinkingblocks that Claude Code renders. - Models that reason internally without streaming (e.g. GPT-5 family) produce no thinking blocks but still bill the reasoning tokens.
- Reasoning shares the
max_tokensbudget. Set a generous value for direct SDK callers. - Turns are slower: expect 20+ seconds for short answers on reasoning models, compared to ~2 seconds on non-reasoning models.
Endpoints
All endpoints are mounted under /anthropic and require X-Api-Key or Authorization: Bearer <JWT> authentication.
| Route | Purpose |
|---|---|
POST /anthropic/v1/messages | Single turn, streaming or non-streaming |
POST /anthropic/v1/messages/count_tokens | Input token estimate without calling a model |
GET /anthropic/v1/models | List available models and agent configurations for your account |
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| "There's an issue with the selected model" | A model slot is unset, misspelled, or still pointing to an Anthropic built-in id. Re-run step 3 and set all seven variables. |
| Same error on turn one of a fresh install | Claude Code sent its default Anthropic model id before you opened /model. The Sonnet or Opus slot is unset. |
connection refused or 401 from an unrecognized gateway | ~/.claude/settings.json has an env block overriding your shell. Run jq '.env' ~/.claude/settings.json. |
/model lists Anthropic names instead of your ids | Unset slots are filled with built-in Anthropic entries. Set all seven variables. |
| Agent configuration uuid stopped working | The agent was recreated and received a new uuid. Resolve by name at startup. |
| Turns are slow (20+ seconds for short answers) | A reasoning model is selected. This is expected behavior. |
429 with rate_limit_error and a message about a monthly BCU cap | Your cap, or the cap of the key's team, is reached. Waiting does not help; a tenant administrator can raise it. See My usage. |